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

package/dist/src/tutorial/tutorialAssertions.js

@@ -0,0 +1,249 @@
+import { readFile, stat } from "node:fs/promises";
+import { resolveTargetFilePath } from "./tutorialPaths.js";
+import { describeTutorialLocator, resolveTutorialLocator } from "./tutorialLocators.js";
+import { DEFAULT_TUTORIAL_ASSERTION_TIMEOUT_MS } from "./types.js";
+/**
+ * RFC 6901 JSON Pointer resolution.
+ *
+ * Deliberately only JSON Pointer: no JSONPath, no dot-notation expression
+ * language, no evaluation. A pointer can address data but can never compute.
+ */
+export function resolveJsonPointer(document, pointer) {
+    if (typeof pointer !== "string") {
+        return { ok: false, error: "JSON Pointer must be a string." };
+    }
+    if (pointer === "") {
+        return { ok: true, value: document };
+    }
+    if (!pointer.startsWith("/")) {
+        return { ok: false, error: `JSON Pointer must be empty or begin with "/"; received ${JSON.stringify(pointer)}.` };
+    }
+    let current = document;
+    const rawTokens = pointer.slice(1).split("/");
+    for (const rawToken of rawTokens) {
+        const badEscape = /~(?![01])/.exec(rawToken);
+        if (badEscape) {
+            return {
+                ok: false,
+                error: `Malformed JSON Pointer escape in segment ${JSON.stringify(rawToken)}; "~" must be followed by "0" or "1".`
+            };
+        }
+        // Order matters: ~1 becomes "/" first, then ~0 becomes "~", so an encoded
+        // "~1" inside a name is not re-interpreted as a separator.
+        const token = rawToken.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (Array.isArray(current)) {
+            if (!/^(0|[1-9][0-9]*)$/.test(token)) {
+                return { ok: false, error: `JSON Pointer segment ${JSON.stringify(token)} is not a valid array index.` };
+            }
+            const index = Number(token);
+            if (index >= current.length) {
+                return { ok: false, error: `JSON Pointer segment ${JSON.stringify(token)} is out of range.` };
+            }
+            current = current[index];
+            continue;
+        }
+        if (typeof current === "object" && current !== null) {
+            if (!Object.prototype.hasOwnProperty.call(current, token)) {
+                return { ok: false, error: `JSON Pointer segment ${JSON.stringify(token)} was not found.` };
+            }
+            current = current[token];
+            continue;
+        }
+        return {
+            ok: false,
+            error: `JSON Pointer segment ${JSON.stringify(token)} cannot be resolved against a non-object value.`
+        };
+    }
+    return { ok: true, value: current };
+}
+/**
+ * Resolves an HTTP assertion path against the application origin and refuses
+ * anything that leaves it. Mirrors the navigation rule so a scenario cannot use
+ * assertions as a general-purpose network client.
+ */
+export function resolveAssertionRequestUrl(applicationUrl, suppliedPath) {
+    if (typeof suppliedPath !== "string" || !suppliedPath.startsWith("/") || suppliedPath.startsWith("//")) {
+        throw new Error(`HTTP assertion path must be a root-relative path beginning with "/" and must not be protocol-relative; received ${JSON.stringify(suppliedPath)}.`);
+    }
+    const base = new URL(applicationUrl);
+    const resolved = new URL(suppliedPath, base);
+    if (resolved.protocol !== base.protocol || resolved.hostname !== base.hostname || resolved.port !== base.port) {
+        throw new Error(`HTTP assertion path ${JSON.stringify(suppliedPath)} resolves to ${resolved.origin}, which leaves the application origin ${base.origin}.`);
+    }
+    return resolved.href;
+}
+export async function executeTutorialAssertion(page, assertion, context) {
+    const startedAtMs = Date.now();
+    const startedAt = new Date(startedAtMs).toISOString();
+    let failure;
+    try {
+        failure = await evaluateAssertion(page, assertion, context);
+    }
+    catch (error) {
+        // An ordinary assertion problem must never escape as an unhandled
+        // exception; it is recorded as a failed assertion result instead.
+        failure = error instanceof Error ? error.message : String(error);
+    }
+    const endedAtMs = Date.now();
+    return {
+        type: assertion.type,
+        status: failure === undefined ? "passed" : "failed",
+        startedAt,
+        endedAt: new Date(endedAtMs).toISOString(),
+        durationMs: endedAtMs - startedAtMs,
+        ...(failure === undefined ? {} : { error: failure })
+    };
+}
+/** Returns undefined when the assertion holds, otherwise a failure message. */
+async function evaluateAssertion(page, assertion, context) {
+    switch (assertion.type) {
+        case "element-visible": {
+            const locator = resolveTutorialLocator(page, assertion.locator);
+            try {
+                await locator.waitFor({ state: "visible", timeout: assertionTimeout(assertion.timeoutMs) });
+                return undefined;
+            }
+            catch (error) {
+                return `Element ${describeTutorialLocator(assertion.locator)} was not visible within ${assertionTimeout(assertion.timeoutMs)}ms: ${messageOf(error)}`;
+            }
+        }
+        case "text-equals":
+        case "text-contains": {
+            const locator = resolveTutorialLocator(page, assertion.locator);
+            const actual = await locator.textContent({ timeout: assertionTimeout(assertion.timeoutMs) });
+            if (actual === null) {
+                return `Element ${describeTutorialLocator(assertion.locator)} has no text content.`;
+            }
+            if (assertion.type === "text-equals") {
+                return actual === assertion.expected
+                    ? undefined
+                    : `Element ${describeTutorialLocator(assertion.locator)} text was ${JSON.stringify(actual)}, expected exactly ${JSON.stringify(assertion.expected)}.`;
+            }
+            return actual.includes(assertion.expected)
+                ? undefined
+                : `Element ${describeTutorialLocator(assertion.locator)} text was ${JSON.stringify(actual)}, expected it to contain ${JSON.stringify(assertion.expected)}.`;
+        }
+        case "url-path-equals": {
+            const actual = comparableUrlPath(page.url(), assertion.expected);
+            return actual === assertion.expected
+                ? undefined
+                : `Page path was ${JSON.stringify(actual)}, expected ${JSON.stringify(assertion.expected)}.`;
+        }
+        case "attribute-equals": {
+            const locator = resolveTutorialLocator(page, assertion.locator);
+            const actual = await locator.getAttribute(assertion.name, {
+                timeout: assertionTimeout(assertion.timeoutMs)
+            });
+            if (actual === null) {
+                return `Element ${describeTutorialLocator(assertion.locator)} has no ${JSON.stringify(assertion.name)} attribute.`;
+            }
+            return actual === assertion.expected
+                ? undefined
+                : `Element ${describeTutorialLocator(assertion.locator)} attribute ${JSON.stringify(assertion.name)} was ${JSON.stringify(actual)}, expected ${JSON.stringify(assertion.expected)}.`;
+        }
+        case "http-json-equals": {
+            const url = resolveAssertionRequestUrl(context.applicationUrl, assertion.path);
+            const timeoutMs = assertionTimeout(assertion.timeoutMs);
+            let response;
+            try {
+                response = await fetch(url, { redirect: "manual", signal: AbortSignal.timeout(timeoutMs) });
+            }
+            catch (error) {
+                return `HTTP assertion request to ${assertion.path} failed: ${messageOf(error)}`;
+            }
+            if (response.status < 200 || response.status > 299) {
+                await response.body?.cancel().catch(() => undefined);
+                return `HTTP assertion request to ${assertion.path} returned status ${response.status}; expected a 2xx response.`;
+            }
+            let body;
+            try {
+                body = await response.text();
+            }
+            catch (error) {
+                return `HTTP assertion response body for ${assertion.path} could not be read: ${messageOf(error)}`;
+            }
+            let document;
+            try {
+                document = JSON.parse(body);
+            }
+            catch (error) {
+                return `HTTP assertion response body for ${assertion.path} is not valid JSON: ${messageOf(error)}`;
+            }
+            return compareAtPointer(document, assertion.pointer, assertion.expected, `${assertion.path}`);
+        }
+        case "json-file-equals": {
+            const filePath = resolveTargetFilePath(context.targetRoot, assertion.path);
+            let raw;
+            try {
+                raw = await readFile(filePath, "utf8");
+            }
+            catch (error) {
+                return `JSON file assertion could not read ${assertion.path}: ${messageOf(error)}`;
+            }
+            let document;
+            try {
+                document = JSON.parse(raw);
+            }
+            catch (error) {
+                return `JSON file ${assertion.path} is not valid JSON: ${messageOf(error)}`;
+            }
+            return compareAtPointer(document, assertion.pointer, assertion.expected, assertion.path);
+        }
+        case "file-exists": {
+            const filePath = resolveTargetFilePath(context.targetRoot, assertion.path);
+            try {
+                const stats = await stat(filePath);
+                if (!stats.isFile()) {
+                    return `Expected ${assertion.path} to be a regular file beneath the tutorial target root, but it is a directory.`;
+                }
+                return undefined;
+            }
+            catch (error) {
+                return `Expected file ${assertion.path} to exist beneath the tutorial target root: ${messageOf(error)}`;
+            }
+        }
+    }
+}
+function compareAtPointer(document, pointer, expected, sourceLabel) {
+    const resolved = resolveJsonPointer(document, pointer);
+    if (!resolved.ok) {
+        return `JSON Pointer ${JSON.stringify(pointer)} did not resolve in ${sourceLabel}: ${resolved.error}`;
+    }
+    const actual = resolved.value;
+    if (actual !== null &&
+        typeof actual !== "string" &&
+        typeof actual !== "number" &&
+        typeof actual !== "boolean") {
+        return `JSON Pointer ${JSON.stringify(pointer)} in ${sourceLabel} resolved to a non-scalar value; expected ${JSON.stringify(expected)}.`;
+    }
+    return actual === expected
+        ? undefined
+        : `JSON Pointer ${JSON.stringify(pointer)} in ${sourceLabel} was ${JSON.stringify(actual)}, expected ${JSON.stringify(expected)}.`;
+}
+/**
+ * Compares only the path portion of the current URL, extended with query and
+ * hash when (and only when) the expectation asks for them. The host is never
+ * compared because the origin is already constrained by navigation policy.
+ */
+export function comparableUrlPath(currentUrl, expected) {
+    let parsed;
+    try {
+        parsed = new URL(currentUrl);
+    }
+    catch {
+        return currentUrl;
+    }
+    if (expected.includes("#")) {
+        return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+    }
+    if (expected.includes("?")) {
+        return `${parsed.pathname}${parsed.search}`;
+    }
+    return parsed.pathname;
+}
+function assertionTimeout(timeoutMs) {
+    return timeoutMs ?? DEFAULT_TUTORIAL_ASSERTION_TIMEOUT_MS;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/tutorial/tutorialCursor.js

@@ -0,0 +1,149 @@
+/**
+ * Synthetic tutorial cursor and click feedback.
+ *
+ * Everything this module injects is presentation only. Playwright still performs
+ * every real interaction, locator resolution and assertion; the cursor exists so
+ * a viewer of the recording can see where the tutorial is pointing. All injected
+ * nodes use `pointer-events: none` so they can never intercept application input,
+ * and they live in one tutorial-owned container so cleanup is a single removal.
+ */
+/** Stable, collision-resistant identities owned by the tutorial runtime. */
+export const TUTORIAL_VISUAL_ROOT_ID = "__my_dev_kit_lab_tutorial_visuals__";
+export const TUTORIAL_CURSOR_ID = "__my_dev_kit_lab_tutorial_cursor__";
+export const TUTORIAL_CLICK_FEEDBACK_ID = "__my_dev_kit_lab_tutorial_click_feedback__";
+/** Planner-owned, machine-independent so recordings are reproducible. */
+export const CURSOR_MOVE_DURATION_MS = 250;
+export const CLICK_FEEDBACK_DURATION_MS = 300;
+const CURSOR_SIZE_PX = 24;
+const CLICK_FEEDBACK_SIZE_PX = 44;
+/** Center of a bounding box; the deterministic cursor target for every action. */
+export function centerOfBox(box) {
+    return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+}
+export function installCursorInPage(arg) {
+    const doc = globalThis.document;
+    if (!doc || !doc.body) {
+        return false;
+    }
+    let root = doc.getElementById(arg.rootId);
+    if (!root) {
+        root = doc.createElement("div");
+        root.id = arg.rootId;
+        root.setAttribute("aria-hidden", "true");
+        root.style.setProperty("position", "fixed");
+        root.style.setProperty("left", "0");
+        root.style.setProperty("top", "0");
+        root.style.setProperty("width", "0");
+        root.style.setProperty("height", "0");
+        root.style.setProperty("pointer-events", "none");
+        root.style.setProperty("z-index", "2147483646");
+        doc.body.appendChild(root);
+    }
+    if (doc.getElementById(arg.cursorId)) {
+        // Installing twice must not produce two cursors.
+        return false;
+    }
+    const cursor = doc.createElement("div");
+    cursor.id = arg.cursorId;
+    cursor.setAttribute("aria-hidden", "true");
+    cursor.style.setProperty("position", "fixed");
+    cursor.style.setProperty("left", "0");
+    cursor.style.setProperty("top", "0");
+    cursor.style.setProperty("width", `${arg.sizePx}px`);
+    cursor.style.setProperty("height", `${arg.sizePx}px`);
+    cursor.style.setProperty("margin-left", `${-arg.sizePx / 2}px`);
+    cursor.style.setProperty("margin-top", `${-arg.sizePx / 2}px`);
+    cursor.style.setProperty("border-radius", "50%");
+    cursor.style.setProperty("background", "rgba(20, 20, 20, 0.35)");
+    cursor.style.setProperty("border", "2px solid rgba(255, 255, 255, 0.9)");
+    cursor.style.setProperty("box-shadow", "0 0 0 1px rgba(0, 0, 0, 0.45)");
+    cursor.style.setProperty("pointer-events", "none");
+    cursor.style.setProperty("z-index", "2147483647");
+    cursor.style.setProperty("opacity", "0");
+    cursor.style.setProperty("transform", "translate(0px, 0px)");
+    cursor.style.setProperty("transition", `transform ${arg.moveDurationMs}ms linear, opacity 120ms linear`);
+    root.appendChild(cursor);
+    return true;
+}
+export function moveCursorInPage(arg) {
+    const doc = globalThis.document;
+    const cursor = doc?.getElementById(arg.cursorId);
+    if (!cursor) {
+        return false;
+    }
+    cursor.style.setProperty("opacity", "1");
+    cursor.style.setProperty("transform", `translate(${arg.x}px, ${arg.y}px)`);
+    return true;
+}
+export function showClickFeedbackInPage(arg) {
+    const doc = globalThis.document;
+    const root = doc?.getElementById(arg.rootId);
+    if (!root) {
+        return false;
+    }
+    // A previous ripple is replaced rather than accumulated.
+    const stale = doc.getElementById(arg.feedbackId);
+    if (stale) {
+        stale.remove();
+    }
+    const ripple = doc.createElement("div");
+    ripple.id = arg.feedbackId;
+    ripple.setAttribute("aria-hidden", "true");
+    ripple.style.setProperty("position", "fixed");
+    ripple.style.setProperty("left", `${arg.x - arg.sizePx / 2}px`);
+    ripple.style.setProperty("top", `${arg.y - arg.sizePx / 2}px`);
+    ripple.style.setProperty("width", `${arg.sizePx}px`);
+    ripple.style.setProperty("height", `${arg.sizePx}px`);
+    ripple.style.setProperty("border-radius", "50%");
+    ripple.style.setProperty("border", "3px solid rgba(255, 92, 0, 0.95)");
+    ripple.style.setProperty("background", "rgba(255, 92, 0, 0.18)");
+    ripple.style.setProperty("pointer-events", "none");
+    ripple.style.setProperty("z-index", "2147483647");
+    root.appendChild(ripple);
+    const timers = globalThis;
+    if (typeof timers.setTimeout === "function") {
+        timers.setTimeout(() => {
+            const current = doc.getElementById(arg.feedbackId);
+            if (current) {
+                current.remove();
+            }
+        }, arg.durationMs);
+    }
+    return true;
+}
+export function removeTutorialVisualsInPage(arg) {
+    const doc = globalThis.document;
+    const root = doc?.getElementById(arg.rootId);
+    if (!root) {
+        return false;
+    }
+    root.remove();
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Host-side helpers
+// ---------------------------------------------------------------------------
+export async function installTutorialCursor(page) {
+    return page.evaluate(installCursorInPage, {
+        rootId: TUTORIAL_VISUAL_ROOT_ID,
+        cursorId: TUTORIAL_CURSOR_ID,
+        moveDurationMs: CURSOR_MOVE_DURATION_MS,
+        sizePx: CURSOR_SIZE_PX
+    });
+}
+export async function moveTutorialCursor(page, point) {
+    return page.evaluate(moveCursorInPage, { cursorId: TUTORIAL_CURSOR_ID, x: point.x, y: point.y });
+}
+export async function showTutorialClickFeedback(page, point) {
+    return page.evaluate(showClickFeedbackInPage, {
+        rootId: TUTORIAL_VISUAL_ROOT_ID,
+        feedbackId: TUTORIAL_CLICK_FEEDBACK_ID,
+        x: point.x,
+        y: point.y,
+        durationMs: CLICK_FEEDBACK_DURATION_MS,
+        sizePx: CLICK_FEEDBACK_SIZE_PX
+    });
+}
+export async function removeTutorialVisuals(page) {
+    return page.evaluate(removeTutorialVisualsInPage, { rootId: TUTORIAL_VISUAL_ROOT_ID });
+}

package/dist/src/tutorial/tutorialLocators.js

@@ -0,0 +1,37 @@
+/**
+ * The single place a declarative locator becomes a Playwright locator.
+ *
+ * Actions, assertions, and (in a later batch) overlay targeting all call this,
+ * so locator semantics cannot drift between them and a new locator kind has
+ * exactly one implementation site.
+ */
+export function resolveTutorialLocator(page, locator) {
+    switch (locator.kind) {
+        case "role":
+            return page.getByRole(locator.role, {
+                ...(locator.name !== undefined ? { name: locator.name } : {}),
+                ...(locator.exact !== undefined ? { exact: locator.exact } : {})
+            });
+        case "text":
+            return page.getByText(locator.text, locator.exact !== undefined ? { exact: locator.exact } : undefined);
+        case "css":
+            return page.locator(locator.selector);
+        case "test-id":
+            return page.getByTestId(locator.testId);
+    }
+}
+/** Short human-readable form used in action and assertion failure messages. */
+export function describeTutorialLocator(locator) {
+    switch (locator.kind) {
+        case "role":
+            return locator.name === undefined
+                ? `role=${locator.role}`
+                : `role=${locator.role} name=${JSON.stringify(locator.name)}`;
+        case "text":
+            return `text=${JSON.stringify(locator.text)}`;
+        case "css":
+            return `css=${locator.selector}`;
+        case "test-id":
+            return `test-id=${locator.testId}`;
+    }
+}

package/dist/src/tutorial/tutorialManifest.js

@@ -0,0 +1,74 @@
+/**
+ * Canonical tutorial run manifest.
+ *
+ * Deliberately its own schema rather than an overloaded GalleryManifest: a
+ * tutorial run records step/action/assertion outcomes, a timeline, and artifact
+ * statuses, none of which a gallery index models. It is built from the
+ * structured runtime results that are already in hand -- output directories are
+ * scanned only to confirm the size of files this run itself wrote.
+ */
+export const TUTORIAL_MANIFEST_SCHEMA_VERSION = "1.0.0";
+export function buildTutorialManifest(options) {
+    const stepById = new Map(options.scenario.steps.map((step) => [step.id, step]));
+    const screenshotRecordById = new Map(options.artifacts
+        .filter((record) => record.kind === "screenshot" && record.id !== undefined)
+        .map((record) => [record.id, record]));
+    // Step order is scenario order; assertion order is execution order. Neither is
+    // re-sorted, so a diff between two runs stays readable.
+    const steps = options.steps.map((stepResult) => {
+        const step = stepById.get(stepResult.id);
+        const requestedScreenshotId = step?.screenshot?.id;
+        const record = requestedScreenshotId ? screenshotRecordById.get(requestedScreenshotId) : undefined;
+        return {
+            id: stepResult.id,
+            status: stepResult.status,
+            narration: step?.narration ?? "",
+            ...(stepResult.timelineStartMs !== undefined ? { timelineStartMs: stepResult.timelineStartMs } : {}),
+            ...(stepResult.timelineEndMs !== undefined ? { timelineEndMs: stepResult.timelineEndMs } : {}),
+            ...(stepResult.action ? { action: stepResult.action } : {}),
+            assertions: stepResult.assertions,
+            ...(stepResult.screenshotRequested || record
+                ? {
+                    screenshot: {
+                        requested: stepResult.screenshotRequested,
+                        ...(requestedScreenshotId !== undefined ? { id: requestedScreenshotId } : {}),
+                        ...(record?.status !== undefined ? { status: record.status } : {}),
+                        ...(record?.path !== undefined ? { path: record.path } : {}),
+                        ...(record?.error !== undefined ? { error: record.error } : {})
+                    }
+                }
+                : {}),
+            highlightRequested: stepResult.highlightRequested,
+            calloutRequested: stepResult.calloutRequested,
+            ...(stepResult.error !== undefined ? { error: stepResult.error } : {})
+        };
+    });
+    return {
+        schemaVersion: TUTORIAL_MANIFEST_SCHEMA_VERSION,
+        scenario: {
+            schemaVersion: options.scenario.schemaVersion,
+            id: options.scenario.id,
+            title: options.scenario.title,
+            ...(options.scenario.description !== undefined ? { description: options.scenario.description } : {}),
+            targetId: options.scenario.targetId
+        },
+        target: {
+            schemaVersion: options.targetContract.schemaVersion,
+            id: options.targetContract.id,
+            applicationUrl: options.targetContract.applicationUrl
+        },
+        run: { ...options.run },
+        environment: options.environment ?? {
+            platform: process.platform,
+            nodeVersion: process.version
+        },
+        steps,
+        artifacts: [...options.artifacts],
+        warnings: [...options.warnings],
+        cleanupErrors: [...options.cleanupErrors]
+    };
+}
+/** Pretty JSON with a single trailing newline. */
+export function renderTutorialManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}