@dailephd/my-dev-kit-lab 0.4.6 → 0.4.8

package/dist/src/tutorial/tutorialSession.js

@@ -0,0 +1,424 @@
+import { existsSync } from "node:fs";
+import { executeTutorialAction } from "./tutorialActions.js";
+import { executeTutorialAssertion } from "./tutorialAssertions.js";
+import { resolveTutorialLocator, describeTutorialLocator } from "./tutorialLocators.js";
+import { resolveTutorialFractionPoint } from "./tutorialPointerGeometry.js";
+import { buildScreenshotPath, toRunRelativePosixPath, verifyArtifactFile } from "./tutorialArtifacts.js";
+import { CLICK_FEEDBACK_DURATION_MS, CURSOR_MOVE_DURATION_MS, centerOfBox, installTutorialCursor, moveTutorialCursor, removeTutorialVisuals, showTutorialClickFeedback } from "./tutorialCursor.js";
+import { applyTutorialCallout, applyTutorialHighlight, clearTutorialStepOverlays, resolveCalloutPlacement } from "./tutorialOverlay.js";
+export async function openTutorialSession(browser, options) {
+    if (typeof browser.newContext !== "function") {
+        return {
+            ok: false,
+            error: "Tutorial browser runtime does not support browser contexts, which a persistent tutorial session requires."
+        };
+    }
+    const viewport = { width: options.viewport.width, height: options.viewport.height };
+    let context;
+    try {
+        context = await browser.newContext({
+            viewport,
+            // Recording size matches the scenario viewport: no invented dimensions.
+            ...(options.recordVideoDir !== undefined
+                ? { recordVideo: { dir: options.recordVideoDir, size: { ...viewport } } }
+                : {})
+        });
+    }
+    catch (error) {
+        return { ok: false, error: `Tutorial browser context could not be created: ${messageOf(error)}` };
+    }
+    try {
+        const page = await context.newPage();
+        let video = null;
+        if (typeof page.video === "function") {
+            try {
+                video = page.video();
+            }
+            catch (error) {
+                // A runtime without video must not prevent the tutorial from running;
+                // the missing recording is reported later as an artifact outcome.
+                video = null;
+                void error;
+            }
+        }
+        return { ok: true, session: { context, page, video } };
+    }
+    catch (error) {
+        await closeQuietly(() => context.close());
+        return { ok: false, error: `Tutorial page could not be created: ${messageOf(error)}` };
+    }
+}
+/**
+ * Closes the page and context. Playwright only finalizes a recording when the
+ * page closes, so the caller finalizes video after this returns.
+ *
+ * Returns cleanup errors rather than throwing so the caller can preserve a
+ * primary failure and still record what went wrong during teardown.
+ */
+export async function closeTutorialSession(session) {
+    const errors = [];
+    if (typeof session.page.close === "function") {
+        const pageError = await closeQuietly(() => session.page.close());
+        if (pageError) {
+            errors.push(`Tutorial page close failed: ${pageError}`);
+        }
+    }
+    const contextError = await closeQuietly(() => session.context.close());
+    if (contextError) {
+        errors.push(`Tutorial browser context close failed: ${contextError}`);
+    }
+    return errors;
+}
+/**
+ * Runs every step in declared order against one page.
+ *
+ * Failure semantics, in the planner's order: an action failure skips that step's
+ * assertions; assertion failures do not short-circuit each other within the same
+ * step (all are collected so a reader sees the full picture); either kind of
+ * failure stops later steps, which are reported as "not-run" rather than omitted
+ * or reported as passed.
+ *
+ * Per-step ordering with visuals enabled:
+ *   clear previous overlays -> pauseBefore -> cursor move -> real action ->
+ *   click feedback -> assertions -> highlight + callout -> pauseAfter ->
+ *   screenshot
+ * so a screenshot always shows the final intended state of its step.
+ */
+export async function executeTutorialSteps(options) {
+    const sleep = options.sleep ?? defaultSleep;
+    const now = options.now ?? Date.now;
+    const timelineOrigin = now();
+    const steps = [];
+    const screenshots = [];
+    const visualWarnings = [];
+    let failedStepId;
+    let failureMessage;
+    /**
+     * Installing is idempotent, and a navigation replaces the whole document, so
+     * the tutorial-owned visual root has to be re-established rather than assumed
+     * to survive. Calling this at the start of every step and again after a
+     * successful goto keeps the cursor present without tracking navigations.
+     */
+    const ensureVisuals = async (stepId) => {
+        if (!options.visuals) {
+            return;
+        }
+        await runVisual(visualWarnings, stepId, "install cursor", () => installTutorialCursor(options.page));
+    };
+    await ensureVisuals("<session>");
+    for (const step of options.scenario.steps) {
+        if (failedStepId !== undefined) {
+            steps.push(notRunStepResult(step));
+            continue;
+        }
+        const startedAtMs = Date.now();
+        const timelineStartMs = Math.max(0, now() - timelineOrigin);
+        const result = {
+            id: step.id,
+            status: "passed",
+            startedAt: new Date(startedAtMs).toISOString(),
+            timelineStartMs,
+            assertions: [],
+            screenshotRequested: step.screenshot !== undefined,
+            highlightRequested: step.highlight !== undefined,
+            calloutRequested: step.callout !== undefined
+        };
+        if (options.visuals) {
+            // Each step starts from a clean visual slate, on a guaranteed-present root.
+            await ensureVisuals(step.id);
+            await runVisual(visualWarnings, step.id, "clear overlays", () => clearTutorialStepOverlays(options.page));
+        }
+        if (step.pauseBeforeMs !== undefined && step.pauseBeforeMs > 0) {
+            await sleep(step.pauseBeforeMs);
+        }
+        let actionPhaseCompleted = true;
+        if (step.action) {
+            const cursorTarget = options.visuals
+                ? await moveCursorForAction(options, step.action, visualWarnings, step.id, sleep)
+                : undefined;
+            const actionResult = await executeTutorialAction(options.page, step.action, {
+                applicationUrl: options.applicationUrl
+            });
+            result.action = actionResult;
+            if (actionResult.status === "failed") {
+                actionPhaseCompleted = false;
+                result.status = "failed";
+                result.error = `Step ${JSON.stringify(step.id)} failed because the ${step.action.type} action failed: ${actionResult.error ?? "unknown error"}`;
+            }
+            else if (options.visuals) {
+                if (step.action.type === "goto") {
+                    // The new document has none of the tutorial's DOM.
+                    await ensureVisuals(step.id);
+                }
+                await applyPostActionVisuals(options, step, cursorTarget, visualWarnings, sleep);
+            }
+        }
+        if (actionPhaseCompleted) {
+            const assertionResults = await runStepAssertions(step, options);
+            result.assertions = assertionResults;
+            const failedAssertions = assertionResults.filter((assertion) => assertion.status === "failed");
+            if (failedAssertions.length > 0) {
+                result.status = "failed";
+                result.error = `Step ${JSON.stringify(step.id)} failed because ${failedAssertions.length} of ${assertionResults.length} assertions failed: ${failedAssertions
+                    .map((assertion) => `${assertion.type}: ${assertion.error ?? "unknown error"}`)
+                    .join("; ")}`;
+            }
+            if (options.visuals) {
+                await applyStepOverlays(options, step, visualWarnings);
+            }
+            if (step.pauseAfterMs !== undefined && step.pauseAfterMs > 0) {
+                await sleep(step.pauseAfterMs);
+            }
+        }
+        if (step.screenshot) {
+            screenshots.push(await captureStepScreenshot(options, step, actionPhaseCompleted));
+        }
+        const endedAtMs = Date.now();
+        result.endedAt = new Date(endedAtMs).toISOString();
+        result.durationMs = endedAtMs - startedAtMs;
+        result.timelineEndMs = Math.max(timelineStartMs, now() - timelineOrigin);
+        steps.push(result);
+        if (result.status === "failed") {
+            failedStepId = step.id;
+            failureMessage = result.error;
+        }
+    }
+    if (options.visuals) {
+        await runVisual(visualWarnings, "<cleanup>", "remove tutorial visuals", () => removeTutorialVisuals(options.page));
+    }
+    return {
+        steps,
+        screenshots,
+        visualWarnings,
+        ...(failedStepId !== undefined ? { failedStepId } : {}),
+        ...(failureMessage !== undefined ? { error: failureMessage } : {})
+    };
+}
+/**
+ * Moves the synthetic cursor onto the action's target before the real action.
+ *
+ * `goto` and `wait-for` have no pointer target, so the cursor is left alone. A
+ * missing bounding box is recorded as a visual warning and the real action still
+ * runs -- presentation never gates correctness.
+ */
+async function moveCursorForAction(options, action, warnings, stepId, sleep) {
+    const locator = cursorLocatorForAction(action);
+    if (!locator) {
+        return undefined;
+    }
+    const box = await readBoundingBox(options.page, locator, warnings, stepId);
+    if (!box) {
+        return undefined;
+    }
+    let point;
+    let pointerDragEnd;
+    try {
+        if (action.type === "pointer-click") {
+            point = resolveTutorialFractionPoint(box, action.position);
+        }
+        else if (action.type === "pointer-drag") {
+            point = resolveTutorialFractionPoint(box, action.from);
+            pointerDragEnd = resolveTutorialFractionPoint(box, action.to);
+        }
+        else {
+            point = centerOfBox(box);
+        }
+    }
+    catch (error) {
+        warnings.push(`Step ${JSON.stringify(stepId)}: pointer visual for ${describeTutorialLocator(locator)} could not be planned: ${messageOf(error)}`);
+        return undefined;
+    }
+    await runVisual(warnings, stepId, "move cursor", () => moveTutorialCursor(options.page, point));
+    await sleep(CURSOR_MOVE_DURATION_MS);
+    return { point, ...(pointerDragEnd ? { pointerDragEnd } : {}) };
+}
+/** The locator whose center the cursor points at before each action type. */
+export function cursorLocatorForAction(action) {
+    switch (action.type) {
+        case "click":
+        case "fill":
+        case "press":
+        case "hover":
+        case "pointer-click":
+        case "pointer-drag":
+            return action.locator;
+        case "drag":
+            return action.source;
+        // goto has no element target; wait-for deliberately does not move the cursor.
+        case "goto":
+        case "wait-for":
+            return undefined;
+    }
+}
+async function applyPostActionVisuals(options, step, cursorTarget, warnings, sleep) {
+    const action = step.action;
+    if (!action) {
+        return;
+    }
+    if ((action.type === "click" || action.type === "pointer-click") && cursorTarget) {
+        await runVisual(warnings, step.id, "click feedback", () => showTutorialClickFeedback(options.page, cursorTarget.point));
+        // Held only long enough for the ripple to be visible in the recording.
+        await sleep(CLICK_FEEDBACK_DURATION_MS);
+        return;
+    }
+    if (action.type === "drag") {
+        // The cursor follows to the drop target after the real drag completed.
+        const box = await readBoundingBox(options.page, action.target, warnings, step.id);
+        if (box) {
+            await runVisual(warnings, step.id, "move cursor to drag target", () => moveTutorialCursor(options.page, centerOfBox(box)));
+            await sleep(CURSOR_MOVE_DURATION_MS);
+        }
+        return;
+    }
+    if (action.type === "pointer-drag" && cursorTarget?.pointerDragEnd) {
+        await runVisual(warnings, step.id, "move cursor to pointer-drag endpoint", () => moveTutorialCursor(options.page, cursorTarget.pointerDragEnd));
+        await sleep(CURSOR_MOVE_DURATION_MS);
+    }
+}
+async function applyStepOverlays(options, step, warnings) {
+    if (step.highlight) {
+        const box = await readBoundingBox(options.page, step.highlight, warnings, step.id);
+        if (box) {
+            await runVisual(warnings, step.id, "apply highlight", () => applyTutorialHighlight(options.page, box));
+        }
+    }
+    if (step.callout) {
+        const box = step.callout.locator
+            ? await readBoundingBox(options.page, step.callout.locator, warnings, step.id)
+            : undefined;
+        const viewport = options.scenario.browser.viewport;
+        const placement = resolveCalloutPlacement(step.callout.placement, box, viewport);
+        await runVisual(warnings, step.id, "apply callout", () => applyTutorialCallout(options.page, {
+            text: step.callout.text,
+            placement,
+            box: box ?? null,
+            viewport
+        }));
+    }
+}
+/**
+ * Captures a requested screenshot from the already-open tutorial page.
+ *
+ * Never launches a browser and never re-navigates: the point of the capture is
+ * the live state this session just produced.
+ */
+async function captureStepScreenshot(options, step, actionPhaseCompleted) {
+    const screenshot = step.screenshot;
+    if (!options.paths) {
+        return {
+            kind: "screenshot",
+            id: screenshot.id,
+            status: "failed",
+            error: `Screenshot ${JSON.stringify(screenshot.id)} was requested but the tutorial run has no screenshot output directory.`
+        };
+    }
+    const absolutePath = buildScreenshotPath(options.paths, screenshot.id);
+    const relativePath = toRunRelativePosixPath(options.paths.runRoot, absolutePath);
+    if (!actionPhaseCompleted) {
+        // The step never reached a usable state; fabricating an image would misrepresent it.
+        return {
+            kind: "screenshot",
+            id: screenshot.id,
+            status: "skipped",
+            path: relativePath,
+            error: `Screenshot ${JSON.stringify(screenshot.id)} was not captured because step ${JSON.stringify(step.id)} failed before reaching a usable state.`
+        };
+    }
+    if (existsSync(absolutePath)) {
+        // Canonical screenshot identity is stable; silently overwriting or adding a
+        // suffix would both hide a real problem.
+        return {
+            kind: "screenshot",
+            id: screenshot.id,
+            status: "failed",
+            path: relativePath,
+            error: `Screenshot ${JSON.stringify(screenshot.id)} already exists at ${relativePath}; refusing to overwrite a canonical tutorial artifact.`
+        };
+    }
+    try {
+        await options.page.screenshot({ path: absolutePath, fullPage: screenshot.fullPage ?? false });
+    }
+    catch (error) {
+        return {
+            kind: "screenshot",
+            id: screenshot.id,
+            status: "failed",
+            path: relativePath,
+            error: `Screenshot ${JSON.stringify(screenshot.id)} could not be captured: ${messageOf(error)}`
+        };
+    }
+    const check = await verifyArtifactFile(absolutePath);
+    if (!check.ok) {
+        return { kind: "screenshot", id: screenshot.id, status: "failed", path: relativePath, error: check.error };
+    }
+    return {
+        kind: "screenshot",
+        id: screenshot.id,
+        status: "written",
+        path: relativePath,
+        sizeBytes: check.sizeBytes
+    };
+}
+async function readBoundingBox(page, locator, warnings, stepId) {
+    try {
+        const box = await resolveTutorialLocator(page, locator).boundingBox();
+        if (!box) {
+            warnings.push(`Step ${JSON.stringify(stepId)}: ${describeTutorialLocator(locator)} has no bounding box, so its tutorial visual was skipped.`);
+            return undefined;
+        }
+        return box;
+    }
+    catch (error) {
+        warnings.push(`Step ${JSON.stringify(stepId)}: bounding box for ${describeTutorialLocator(locator)} could not be read: ${messageOf(error)}`);
+        return undefined;
+    }
+}
+/**
+ * Runs one presentation operation. A failure here is recorded as a visual
+ * warning, never swallowed and never promoted into an action/assertion outcome.
+ */
+async function runVisual(warnings, stepId, description, operation) {
+    try {
+        await operation();
+    }
+    catch (error) {
+        warnings.push(`Step ${JSON.stringify(stepId)}: tutorial visual "${description}" failed: ${messageOf(error)}`);
+    }
+}
+async function runStepAssertions(step, options) {
+    const results = [];
+    for (const assertion of step.assertions ?? []) {
+        results.push(await executeTutorialAssertion(options.page, assertion, {
+            applicationUrl: options.applicationUrl,
+            targetRoot: options.targetRoot
+        }));
+    }
+    return results;
+}
+function notRunStepResult(step) {
+    return {
+        id: step.id,
+        status: "not-run",
+        assertions: [],
+        screenshotRequested: step.screenshot !== undefined,
+        highlightRequested: step.highlight !== undefined,
+        calloutRequested: step.callout !== undefined
+    };
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+async function closeQuietly(close) {
+    try {
+        await close();
+        return undefined;
+    }
+    catch (error) {
+        return messageOf(error);
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/tutorial/types.js

@@ -0,0 +1,51 @@
+/**
+ * v0.4.7 tutorial domain contracts.
+ *
+ * Everything here is declarative and serializable by design. A scenario can
+ * describe what to do, but it can never carry JavaScript, a shell command, or
+ * an arbitrary URL -- those escape hatches are deliberately absent from the
+ * union types below and are rejected by validation, not merely undocumented.
+ */
+export const TUTORIAL_SCHEMA_VERSION = "1.0.0";
+export const TARGET_CONTRACT_SCHEMA_VERSION = "1.0.0";
+/** Result schema version for TutorialRunResultV1. */
+export const TUTORIAL_RUN_RESULT_SCHEMA_VERSION = "1.0.0";
+export const MAX_TUTORIAL_STEPS = 500;
+export const MAX_STEP_PAUSE_MS = 60_000;
+export const MIN_VIEWPORT_WIDTH = 320;
+export const MAX_VIEWPORT_WIDTH = 3840;
+export const MIN_VIEWPORT_HEIGHT = 240;
+export const MAX_VIEWPORT_HEIGHT = 2160;
+export const DEFAULT_TUTORIAL_ACTION_TIMEOUT_MS = 5_000;
+export const DEFAULT_TUTORIAL_ASSERTION_TIMEOUT_MS = 5_000;
+/** Stable, path-safe, lowercase identifier shape shared by every tutorial id. */
+export const TUTORIAL_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+/** The only placeholder a trusted target contract may use. */
+export const TARGET_ROOT_PLACEHOLDER = "{{targetRoot}}";
+export const TUTORIAL_LOCATOR_KINDS = ["role", "text", "css", "test-id"];
+export const TUTORIAL_POINTER_COORDINATE_SPACES = ["fraction"];
+export const TUTORIAL_ACTION_TYPES = [
+    "goto",
+    "click",
+    "fill",
+    "press",
+    "hover",
+    "drag",
+    "wait-for",
+    "pointer-click",
+    "pointer-drag"
+];
+export const TUTORIAL_GOTO_WAIT_UNTIL = ["load", "domcontentloaded", "networkidle"];
+export const TUTORIAL_WAIT_FOR_STATES = ["visible", "hidden", "attached", "detached"];
+export const TUTORIAL_ASSERTION_TYPES = [
+    "element-visible",
+    "text-equals",
+    "text-contains",
+    "url-path-equals",
+    "attribute-equals",
+    "http-json-equals",
+    "json-file-equals",
+    "file-exists"
+];
+export const TUTORIAL_CALLOUT_PLACEMENTS = ["auto", "top", "right", "bottom", "left"];
+export const TUTORIAL_TARGET_PROCESS_CWDS = ["contract-root", "target-root"];

package/dist/src/tutorial/validationPrimitives.js

@@ -0,0 +1,141 @@
+import { TUTORIAL_ID_PATTERN } from "./types.js";
+export function createErrorCollector(source) {
+    const errors = [];
+    return {
+        add(location, message) {
+            errors.push(`${source} validation failed at ${location}: ${message}`);
+        },
+        get errors() {
+            return errors;
+        },
+        get length() {
+            return errors.length;
+        }
+    };
+}
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function isStableId(value) {
+    return typeof value === "string" && TUTORIAL_ID_PATTERN.test(value);
+}
+/** Finite positive integer. Rejects NaN, Infinity, zero, negatives and floats. */
+export function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+/** Finite non-negative integer. Rejects NaN, Infinity, negatives and floats. */
+export function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+export function isJsonScalar(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)));
+}
+export function describeValue(value) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value))
+        return "an array";
+    if (typeof value === "object")
+        return "an object";
+    return typeof value;
+}
+/**
+ * Enforces the exact supported schema version. Prompt 2 supports 1.0.0 only and
+ * never reinterprets or auto-upgrades another version, including another minor.
+ */
+export function validateSchemaVersion(errors, value, supported) {
+    if (value === undefined) {
+        errors.add("schemaVersion", `missing required schemaVersion; expected "${supported}".`);
+        return;
+    }
+    if (typeof value !== "string") {
+        errors.add("schemaVersion", `expected the string "${supported}", received ${describeValue(value)}.`);
+        return;
+    }
+    if (value !== supported) {
+        errors.add("schemaVersion", `unsupported schemaVersion ${JSON.stringify(value)}; this build supports "${supported}" only.`);
+    }
+}
+export function validateStableId(errors, location, value) {
+    if (!isNonEmptyString(value)) {
+        errors.add(location, `expected a non-empty id string, received ${describeValue(value)}.`);
+        return false;
+    }
+    if (!isStableId(value)) {
+        errors.add(location, `id ${JSON.stringify(value)} must match ${String(TUTORIAL_ID_PATTERN)} (lowercase letters, digits, dot, underscore, hyphen; must start with a letter or digit).`);
+        return false;
+    }
+    return true;
+}
+export function validateStringRecord(errors, location, value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isPlainObject(value)) {
+        errors.add(location, `expected an object of string values, received ${describeValue(value)}.`);
+        return undefined;
+    }
+    let valid = true;
+    for (const [key, entry] of Object.entries(value)) {
+        if (key.length === 0) {
+            errors.add(location, "environment variable names must not be empty.");
+            valid = false;
+            continue;
+        }
+        if (typeof entry !== "string") {
+            errors.add(`${location}.${key}`, `expected a string value, received ${describeValue(entry)}.`);
+            valid = false;
+        }
+    }
+    return valid ? value : undefined;
+}
+export function validateStringArray(errors, location, value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        errors.add(location, `expected an array of strings, received ${describeValue(value)}.`);
+        return undefined;
+    }
+    let valid = true;
+    value.forEach((entry, index) => {
+        if (typeof entry !== "string") {
+            errors.add(`${location}[${index}]`, `expected a string, received ${describeValue(entry)}.`);
+            valid = false;
+        }
+    });
+    return valid ? value : undefined;
+}
+/**
+ * Optional timeout fields must be finite positive integers when supplied. Zero,
+ * negative values, NaN and Infinity are all rejected rather than silently
+ * coerced to a default.
+ */
+export function validateOptionalTimeout(errors, location, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isPositiveInteger(value)) {
+        errors.add(location, `expected a finite positive integer number of milliseconds, received ${describeValue(value)}.`);
+    }
+}
+export function rejectUnknownKeys(errors, location, value, allowed) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!allowedSet.has(key)) {
+            errors.add(`${location}.${key}`, `unknown field ${JSON.stringify(key)} is not part of this contract.`);
+        }
+    }
+}