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

package/dist/src/tutorial/targetContractValidation.js

@@ -0,0 +1,212 @@
+import { TARGET_CONTRACT_SCHEMA_VERSION, TARGET_ROOT_PLACEHOLDER, TUTORIAL_TARGET_PROCESS_CWDS } from "./types.js";
+import { createErrorCollector, describeValue, isNonEmptyString, isPlainObject, isPositiveInteger, rejectUnknownKeys, validateSchemaVersion, validateStableId, validateStringArray, validateStringRecord } from "./validationPrimitives.js";
+const CONTRACT_KEYS = ["schemaVersion", "id", "prepare", "processes", "applicationUrl"];
+const PREPARE_KEYS = ["executable", "args", "env"];
+const PROCESS_KEYS = ["id", "executable", "args", "cwd", "env", "readiness"];
+const READINESS_KEYS = [
+    "kind",
+    "url",
+    "timeoutMs",
+    "intervalMs",
+    "requestTimeoutMs",
+    "acceptedStatusMin",
+    "acceptedStatusMax"
+];
+/**
+ * Fields that would turn a declarative target contract into a shell. They are
+ * already excluded by the closed key lists, but they are named explicitly so the
+ * failure says why rather than only "unknown field".
+ */
+const FORBIDDEN_EXECUTION_FIELDS = ["shell", "commandString", "script", "javascript", "eval", "command"];
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+/**
+ * Validates a parsed JSON value as a TutorialTargetContractV1.
+ *
+ * The target contract is the trusted half of the tutorial system: it is the only
+ * place that may name an executable. That trust is bounded here -- commands are
+ * executable-plus-arguments only, the single permitted placeholder is
+ * {{targetRoot}}, and the application origin must be loopback.
+ */
+export function validateTutorialTargetContract(value, source = "Target contract") {
+    const errors = createErrorCollector(source);
+    if (!isPlainObject(value)) {
+        errors.add("<root>", `expected a JSON object, received ${describeValue(value)}.`);
+        return { ok: false, errors: errors.errors };
+    }
+    rejectForbiddenExecutionFields(errors, "<root>", value);
+    rejectUnknownKeys(errors, "<root>", value, CONTRACT_KEYS);
+    validateSchemaVersion(errors, value.schemaVersion, TARGET_CONTRACT_SCHEMA_VERSION);
+    validateStableId(errors, "id", value.id);
+    validatePrepare(errors, value.prepare);
+    validateProcesses(errors, value.processes);
+    validateApplicationUrl(errors, value.applicationUrl);
+    if (errors.length > 0) {
+        return { ok: false, errors: errors.errors };
+    }
+    return { ok: true, value: value };
+}
+function rejectForbiddenExecutionFields(errors, location, value) {
+    for (const field of FORBIDDEN_EXECUTION_FIELDS) {
+        if (field in value) {
+            errors.add(`${location}.${field}`, `field ${JSON.stringify(field)} is not supported; target commands are declared as an executable plus an argument array and are never interpreted by a shell.`);
+        }
+    }
+}
+function validatePrepare(errors, value) {
+    if (value === undefined) {
+        errors.add("prepare", "a target contract must declare a prepare command.");
+        return;
+    }
+    if (!isPlainObject(value)) {
+        errors.add("prepare", `expected a prepare command object, received ${describeValue(value)}.`);
+        return;
+    }
+    rejectForbiddenExecutionFields(errors, "prepare", value);
+    rejectUnknownKeys(errors, "prepare", value, PREPARE_KEYS);
+    if (!isNonEmptyString(value.executable)) {
+        errors.add("prepare.executable", `expected a non-empty executable name or path, received ${describeValue(value.executable)}.`);
+    }
+    const args = validateStringArray(errors, "prepare.args", value.args);
+    validatePlaceholders(errors, "prepare.args", args);
+    const env = validateStringRecord(errors, "prepare.env", value.env);
+    validateEnvPlaceholders(errors, "prepare.env", env);
+}
+function validateProcesses(errors, value) {
+    if (!Array.isArray(value)) {
+        errors.add("processes", `expected an array of managed processes, received ${describeValue(value)}.`);
+        return;
+    }
+    if (value.length === 0) {
+        errors.add("processes", "a target contract must declare at least one managed process.");
+        return;
+    }
+    const processIds = new Set();
+    value.forEach((entry, index) => {
+        validateProcess(errors, `processes[${index}]`, entry, processIds);
+    });
+}
+function validateProcess(errors, location, value, processIds) {
+    if (!isPlainObject(value)) {
+        errors.add(location, `expected a managed-process object, received ${describeValue(value)}.`);
+        return;
+    }
+    rejectForbiddenExecutionFields(errors, location, value);
+    rejectUnknownKeys(errors, location, value, PROCESS_KEYS);
+    if (validateStableId(errors, `${location}.id`, value.id)) {
+        if (processIds.has(value.id)) {
+            errors.add(`${location}.id`, `duplicate process id ${JSON.stringify(value.id)}.`);
+        }
+        processIds.add(value.id);
+    }
+    if (!isNonEmptyString(value.executable)) {
+        errors.add(`${location}.executable`, `expected a non-empty executable name or path, received ${describeValue(value.executable)}.`);
+    }
+    const args = validateStringArray(errors, `${location}.args`, value.args);
+    validatePlaceholders(errors, `${location}.args`, args);
+    const env = validateStringRecord(errors, `${location}.env`, value.env);
+    validateEnvPlaceholders(errors, `${location}.env`, env);
+    if (value.cwd !== undefined && !TUTORIAL_TARGET_PROCESS_CWDS.includes(value.cwd)) {
+        errors.add(`${location}.cwd`, `expected one of ${TUTORIAL_TARGET_PROCESS_CWDS.join(", ")}, received ${describeValue(value.cwd)}.`);
+    }
+    validateReadiness(errors, `${location}.readiness`, value.readiness);
+}
+function validateReadiness(errors, location, value) {
+    if (!isPlainObject(value)) {
+        errors.add(location, `expected a readiness probe object, received ${describeValue(value)}.`);
+        return;
+    }
+    rejectUnknownKeys(errors, location, value, READINESS_KEYS);
+    if (value.kind !== "http") {
+        errors.add(`${location}.kind`, `expected "http", received ${describeValue(value.kind)}.`);
+    }
+    validateLoopbackUrl(errors, `${location}.url`, value.url);
+    if (!isPositiveInteger(value.timeoutMs)) {
+        errors.add(`${location}.timeoutMs`, `expected a finite positive integer number of milliseconds, received ${describeValue(value.timeoutMs)}.`);
+    }
+    for (const optional of ["intervalMs", "requestTimeoutMs"]) {
+        if (value[optional] !== undefined && !isPositiveInteger(value[optional])) {
+            errors.add(`${location}.${optional}`, `expected a finite positive integer number of milliseconds, received ${describeValue(value[optional])}.`);
+        }
+    }
+    for (const optional of ["acceptedStatusMin", "acceptedStatusMax"]) {
+        if (value[optional] !== undefined && !isPositiveInteger(value[optional])) {
+            errors.add(`${location}.${optional}`, `expected a finite positive integer HTTP status code, received ${describeValue(value[optional])}.`);
+        }
+    }
+    const min = value.acceptedStatusMin;
+    const max = value.acceptedStatusMax;
+    if (isPositiveInteger(min) && isPositiveInteger(max) && min > max) {
+        errors.add(location, `accepted status range is inverted: ${min}..${max}.`);
+    }
+}
+function validateApplicationUrl(errors, value) {
+    validateLoopbackUrl(errors, "applicationUrl", value);
+}
+/**
+ * A tutorial may only drive a local application. Restricting the declared origin
+ * to loopback here is what makes the later same-origin navigation and HTTP
+ * assertion checks meaningful: they can only ever resolve to this machine.
+ */
+function validateLoopbackUrl(errors, location, value) {
+    if (!isNonEmptyString(value)) {
+        errors.add(location, `expected a non-empty URL string, received ${describeValue(value)}.`);
+        return;
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        errors.add(location, `expected a valid absolute URL, received ${JSON.stringify(value)}.`);
+        return;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        errors.add(location, `expected an http: or https: URL, received protocol ${parsed.protocol}.`);
+        return;
+    }
+    const hostname = parsed.hostname.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+    if (!LOOPBACK_HOSTS.has(hostname)) {
+        errors.add(location, `must use a loopback hostname (localhost, 127.0.0.1, ::1); received ${parsed.hostname}.`);
+    }
+}
+function validatePlaceholders(errors, location, values) {
+    if (!values) {
+        return;
+    }
+    values.forEach((entry, index) => {
+        validatePlaceholderText(errors, `${location}[${index}]`, entry);
+    });
+}
+function validateEnvPlaceholders(errors, location, env) {
+    if (!env) {
+        return;
+    }
+    for (const [key, entry] of Object.entries(env)) {
+        validatePlaceholderText(errors, `${location}.${key}`, entry);
+    }
+}
+/**
+ * Only {{targetRoot}} is substituted. Every other `{{...}}` occurrence is a
+ * validation error rather than a literal, so a contract can never rely on a
+ * generic template evaluator that this repository deliberately does not have.
+ */
+function validatePlaceholderText(errors, location, value) {
+    const placeholderPattern = /\{\{([^}]*)\}\}/g;
+    let match;
+    while ((match = placeholderPattern.exec(value)) !== null) {
+        const whole = match[0];
+        if (whole !== TARGET_ROOT_PLACEHOLDER) {
+            errors.add(location, `unsupported placeholder ${JSON.stringify(whole)}; ${TARGET_ROOT_PLACEHOLDER} is the only placeholder this contract supports.`);
+        }
+    }
+}
+/**
+ * Cross-contract identity check. Kept next to target-contract validation because
+ * it is the last gate before any target work happens.
+ */
+export function tutorialTargetIdsMatch(scenarioTargetId, targetContractId) {
+    return scenarioTargetId === targetContractId;
+}
+export function describeTargetIdMismatch(scenarioTargetId, targetContractId) {
+    return `Tutorial scenario targetId ${JSON.stringify(scenarioTargetId)} does not match target contract id ${JSON.stringify(targetContractId)}.`;
+}

package/dist/src/tutorial/tutorialActions.js

@@ -0,0 +1,175 @@
+import { describeTutorialLocator, resolveTutorialLocator } from "./tutorialLocators.js";
+import { resolveTutorialFractionPoint } from "./tutorialPointerGeometry.js";
+import { DEFAULT_TUTORIAL_ACTION_TIMEOUT_MS } from "./types.js";
+export const POINTER_DRAG_MOVE_STEPS = 8;
+/**
+ * Resolves a scenario `goto` path against the target application's URL and
+ * proves the result never leaves that origin.
+ *
+ * Validation already rejects absolute and protocol-relative paths, so this is
+ * the second, authoritative gate: whatever the string is, the resolved URL must
+ * match the application's protocol, hostname and port exactly or navigation is
+ * refused.
+ */
+export function resolveTutorialNavigationUrl(applicationUrl, suppliedPath) {
+    if (typeof suppliedPath !== "string" || !suppliedPath.startsWith("/") || suppliedPath.startsWith("//")) {
+        throw new Error(`Tutorial goto 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(`Tutorial goto path ${JSON.stringify(suppliedPath)} resolves to ${resolved.origin}, which leaves the application origin ${base.origin}.`);
+    }
+    return resolved.href;
+}
+/**
+ * Executes one declarative action and always returns a structured result.
+ *
+ * There is intentionally no retry loop here: Playwright's own per-call timeout
+ * is the single waiting mechanism, so a step's duration stays predictable and a
+ * flaky scenario cannot be masked by silent repetition.
+ */
+export async function executeTutorialAction(page, action, context) {
+    const startedAtMs = Date.now();
+    const startedAt = new Date(startedAtMs).toISOString();
+    try {
+        await performAction(page, action, context);
+        return finish(action.type, "passed", startedAt, startedAtMs);
+    }
+    catch (error) {
+        return {
+            ...finish(action.type, "failed", startedAt, startedAtMs),
+            error: describeActionError(action, error)
+        };
+    }
+}
+async function performAction(page, action, context) {
+    switch (action.type) {
+        case "goto": {
+            const url = resolveTutorialNavigationUrl(context.applicationUrl, action.path);
+            await page.goto(url, action.waitUntil !== undefined ? { waitUntil: action.waitUntil } : undefined);
+            return;
+        }
+        case "click":
+            await resolveTutorialLocator(page, action.locator).click({ timeout: timeoutFor(action.timeoutMs) });
+            return;
+        case "fill":
+            await resolveTutorialLocator(page, action.locator).fill(action.value, {
+                timeout: timeoutFor(action.timeoutMs)
+            });
+            return;
+        case "press":
+            await resolveTutorialLocator(page, action.locator).press(action.key, {
+                timeout: timeoutFor(action.timeoutMs)
+            });
+            return;
+        case "hover":
+            await resolveTutorialLocator(page, action.locator).hover({ timeout: timeoutFor(action.timeoutMs) });
+            return;
+        case "drag": {
+            // Both ends go through the canonical resolver so a drag cannot develop its
+            // own locator semantics.
+            const source = resolveTutorialLocator(page, action.source);
+            const target = resolveTutorialLocator(page, action.target);
+            await source.dragTo(target, { timeout: timeoutFor(action.timeoutMs) });
+            return;
+        }
+        case "pointer-click": {
+            const locator = resolveTutorialLocator(page, action.locator);
+            await locator.waitFor({ state: "visible", timeout: timeoutFor(action.timeoutMs) });
+            const box = await locator.boundingBox();
+            if (!box) {
+                throw new Error("locator has no bounding box");
+            }
+            const point = resolveTutorialFractionPoint(box, action.position);
+            await page.mouse.move(point.x, point.y);
+            await runWithMouseDown(page.mouse, async () => { });
+            return;
+        }
+        case "pointer-drag": {
+            const locator = resolveTutorialLocator(page, action.locator);
+            await locator.waitFor({ state: "visible", timeout: timeoutFor(action.timeoutMs) });
+            const box = await locator.boundingBox();
+            if (!box) {
+                throw new Error("locator has no bounding box");
+            }
+            const start = resolveTutorialFractionPoint(box, action.from);
+            const end = resolveTutorialFractionPoint(box, action.to);
+            await page.mouse.move(start.x, start.y);
+            await runWithMouseDown(page.mouse, () => page.mouse.move(end.x, end.y, { steps: POINTER_DRAG_MOVE_STEPS }));
+            return;
+        }
+        case "wait-for":
+            await resolveTutorialLocator(page, action.locator).waitFor({
+                ...(action.state !== undefined ? { state: action.state } : {}),
+                timeout: timeoutFor(action.timeoutMs)
+            });
+            return;
+    }
+}
+async function runWithMouseDown(mouse, operation) {
+    await mouse.down();
+    let primaryError;
+    let primaryFailed = false;
+    try {
+        await operation();
+    }
+    catch (error) {
+        primaryFailed = true;
+        primaryError = error;
+    }
+    try {
+        await mouse.up();
+    }
+    catch (cleanupError) {
+        if (primaryFailed) {
+            const primaryMessage = messageOf(primaryError);
+            const cleanupMessage = messageOf(cleanupError);
+            throw new Error(`${primaryMessage} (mouse.up cleanup also failed: ${cleanupMessage})`, {
+                cause: primaryError
+            });
+        }
+        throw cleanupError;
+    }
+    if (primaryFailed) {
+        throw primaryError;
+    }
+}
+export function timeoutFor(timeoutMs) {
+    return timeoutMs ?? DEFAULT_TUTORIAL_ACTION_TIMEOUT_MS;
+}
+function finish(type, status, startedAt, startedAtMs) {
+    const endedAtMs = Date.now();
+    return {
+        type,
+        status,
+        startedAt,
+        endedAt: new Date(endedAtMs).toISOString(),
+        durationMs: endedAtMs - startedAtMs
+    };
+}
+function describeActionError(action, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    switch (action.type) {
+        case "goto":
+            return `goto ${JSON.stringify(action.path)} failed: ${message}`;
+        case "drag":
+            return `drag from ${describeTutorialLocator(action.source)} to ${describeTutorialLocator(action.target)} failed: ${message}`;
+        case "pointer-click":
+            return `pointer-click on ${describeTutorialLocator(action.locator)} at fraction ${describeFractionPoint(action.position)} failed: ${message}`;
+        case "pointer-drag":
+            return `pointer-drag on ${describeTutorialLocator(action.locator)} from fraction ${describeFractionPoint(action.from)} to ${describeFractionPoint(action.to)} failed: ${message}`;
+        case "click":
+        case "fill":
+        case "press":
+        case "hover":
+        case "wait-for":
+            return `${action.type} on ${describeTutorialLocator(action.locator)} failed: ${message}`;
+    }
+}
+function describeFractionPoint(point) {
+    return `(${String(point.x)}, ${String(point.y)})`;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/tutorial/tutorialArtifacts.js

@@ -0,0 +1,176 @@
+import { readdir, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveWithinRoot } from "../core/pathSafety.js";
+/**
+ * Canonical tutorial artifact paths, writing, finalization and verification.
+ *
+ * Every artifact this module writes is contained inside the run's own
+ * TutorialRunPaths roots. Nothing here accepts an output path from scenario
+ * JSON: screenshot identity comes from the validated stable-id contract and
+ * everything else has a fixed canonical name.
+ */
+export const TUTORIAL_VIDEO_FILENAME = "tutorial.webm";
+export const TUTORIAL_SRT_FILENAME = "tutorial.srt";
+export const TUTORIAL_VTT_FILENAME = "tutorial.vtt";
+export const TUTORIAL_MARKDOWN_FILENAME = "tutorial.md";
+export const TUTORIAL_MANIFEST_FILENAME = "tutorial-manifest.json";
+/** Subdirectory of temporaryRoot that Playwright records raw video into. */
+export const TUTORIAL_VIDEO_TEMP_DIR_NAME = "video";
+export function buildTutorialArtifactPaths(paths) {
+    return {
+        video: path.join(paths.artifactsRoot, TUTORIAL_VIDEO_FILENAME),
+        srt: path.join(paths.artifactsRoot, TUTORIAL_SRT_FILENAME),
+        vtt: path.join(paths.artifactsRoot, TUTORIAL_VTT_FILENAME),
+        markdown: path.join(paths.artifactsRoot, TUTORIAL_MARKDOWN_FILENAME),
+        manifest: path.join(paths.artifactsRoot, TUTORIAL_MANIFEST_FILENAME),
+        videoTempDir: path.join(paths.temporaryRoot, TUTORIAL_VIDEO_TEMP_DIR_NAME)
+    };
+}
+/**
+ * Absolute path for a validated screenshot id, contained under screenshotsRoot.
+ *
+ * The id has already passed the stable-id pattern, so it cannot contain a
+ * separator or traversal; the containment check is belt-and-braces and would
+ * catch any future loosening of that contract.
+ */
+export function buildScreenshotPath(paths, screenshotId) {
+    return resolveWithinRoot(paths.screenshotsRoot, `${screenshotId}.png`);
+}
+/**
+ * Run-root-relative POSIX path used in every stored artifact record, so a
+ * manifest never carries `C:\Users\...` or `/home/runner/...`.
+ */
+export function toRunRelativePosixPath(runRoot, absolutePath) {
+    return path.relative(path.resolve(runRoot), path.resolve(absolutePath)).split(path.sep).join("/");
+}
+/** Confirms a canonical artifact is a regular file and, when required, non-empty. */
+export async function verifyArtifactFile(filePath, options = {}) {
+    let stats;
+    try {
+        stats = await stat(filePath);
+    }
+    catch (error) {
+        return { ok: false, error: `Artifact file is missing: ${filePath} (${messageOf(error)})` };
+    }
+    if (!stats.isFile()) {
+        return { ok: false, error: `Artifact path is not a regular file: ${filePath}` };
+    }
+    if ((options.requireNonEmpty ?? true) && stats.size === 0) {
+        return { ok: false, error: `Artifact file is empty: ${filePath}` };
+    }
+    return { ok: true, sizeBytes: stats.size };
+}
+/**
+ * Writes one text artifact and verifies it landed, returning a record either way.
+ * A write failure is data, not an exception, so a run can continue to the next
+ * artifact and report every failure together.
+ */
+export async function writeTextArtifact(options) {
+    const relativePath = toRunRelativePosixPath(options.runRoot, options.filePath);
+    try {
+        await writeFile(options.filePath, options.contents, "utf8");
+    }
+    catch (error) {
+        return {
+            kind: options.kind,
+            status: "failed",
+            path: relativePath,
+            error: `Could not write ${relativePath}: ${messageOf(error)}`
+        };
+    }
+    const check = await verifyArtifactFile(options.filePath);
+    if (!check.ok) {
+        return { kind: options.kind, status: "failed", path: relativePath, error: check.error };
+    }
+    return { kind: options.kind, status: "written", path: relativePath, sizeBytes: check.sizeBytes };
+}
+/**
+ * Saves Playwright's recording to the canonical tutorial.webm.
+ *
+ * The page must already be closed: Playwright only finalizes a recording on page
+ * close, so `saveAs()` before that would either hang or produce a truncated
+ * file. On success the raw temporary recording is removed; on failure it is
+ * deliberately retained (and reported) because it is the only diagnostic
+ * material left.
+ */
+export async function finalizeTutorialVideo(options) {
+    const warnings = [];
+    const relativePath = toRunRelativePosixPath(options.runRoot, options.videoPath);
+    if (!options.video) {
+        return {
+            record: {
+                kind: "video",
+                status: "skipped",
+                error: "The tutorial page exposed no recorded video, so no canonical WebM was produced."
+            },
+            warnings
+        };
+    }
+    let rawPath;
+    try {
+        rawPath = await options.video.path();
+    }
+    catch (error) {
+        // Not fatal on its own: saveAs may still work.
+        warnings.push(`Raw tutorial video path could not be resolved: ${messageOf(error)}`);
+    }
+    try {
+        await options.video.saveAs(options.videoPath);
+    }
+    catch (error) {
+        if (rawPath) {
+            warnings.push(`Raw tutorial video retained for diagnosis at ${rawPath}.`);
+        }
+        return {
+            record: {
+                kind: "video",
+                status: "failed",
+                path: relativePath,
+                error: `Tutorial video could not be finalized to ${relativePath}: ${messageOf(error)}`
+            },
+            warnings
+        };
+    }
+    const check = await verifyArtifactFile(options.videoPath);
+    if (!check.ok) {
+        if (rawPath) {
+            warnings.push(`Raw tutorial video retained for diagnosis at ${rawPath}.`);
+        }
+        return {
+            record: { kind: "video", status: "failed", path: relativePath, error: check.error },
+            warnings
+        };
+    }
+    const cleanupWarning = await removeTemporaryVideoFiles(options.videoTempDir);
+    if (cleanupWarning) {
+        warnings.push(cleanupWarning);
+    }
+    return {
+        record: { kind: "video", status: "written", path: relativePath, sizeBytes: check.sizeBytes },
+        warnings
+    };
+}
+/**
+ * Removes raw recordings once the canonical WebM exists, so runs do not
+ * accumulate abandoned temporary video directories. Only the dedicated video
+ * temp directory is touched, never the canonical artifact.
+ */
+export async function removeTemporaryVideoFiles(videoTempDir) {
+    try {
+        const entries = await readdir(videoTempDir);
+        await Promise.all(entries
+            .filter((entry) => entry.toLowerCase().endsWith(".webm"))
+            .map((entry) => rm(path.join(videoTempDir, entry), { force: true })));
+        return undefined;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT") {
+            return undefined;
+        }
+        return `Temporary tutorial video files under ${videoTempDir} could not be removed: ${messageOf(error)}`;
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}