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

package/dist/src/screenshot/captureReportScreenshot.js

@@ -1,25 +1,23 @@
 import { access } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { closeBrowserQuietly, errorMessage, isMissingBrowserRuntimeError, launchChromium } from "../browser/index.js";
 const SKIP_WARNING = "PNG screenshot skipped because Playwright or browser runtime is unavailable.";
-function isMissingBrowserRuntime(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return (message.includes("Executable doesn't exist") ||
-        message.includes("browserType.launch") ||
-        message.includes("playwright install") ||
-        message.includes("Failed to launch") ||
-        message.includes("Could not find Chrome") ||
-        message.includes("ENOENT"));
-}
-async function defaultLoadPlaywright() {
-    return (await import("playwright"));
-}
+const REPORT_VIEWPORT = { width: 1440, height: 1080 };
+/**
+ * Captures a one-shot PNG of a local HTML report.
+ *
+ * Playwright loading, Chromium launch, and browser-availability classification
+ * are owned by `src/browser`; this module owns only the report-specific policy
+ * of mapping a generic runtime outcome onto captured/skipped/failed. A missing
+ * Playwright package and a missing Chromium binary are both non-fatal for a
+ * report (the HTML report is still produced), so both become "skipped".
+ */
 export async function captureReportScreenshot(htmlPath, pngPath, options) {
-    const loadPlaywright = options?.loadPlaywright ?? defaultLoadPlaywright;
     try {
         await access(htmlPath);
     }
-    catch (error) {
+    catch {
         return {
             status: "failed",
             htmlPath,
@@ -27,11 +25,8 @@ export async function captureReportScreenshot(htmlPath, pngPath, options) {
             error: `HTML report not found: ${htmlPath}`
         };
     }
-    let playwright;
-    try {
-        playwright = await loadPlaywright();
-    }
-    catch {
+    const launch = await launchChromium({ headless: true, loadPlaywright: options?.loadPlaywright });
+    if (launch.status === "unavailable") {
         return {
             status: "skipped",
             htmlPath,
@@ -39,10 +34,17 @@ export async function captureReportScreenshot(htmlPath, pngPath, options) {
             warning: SKIP_WARNING
         };
     }
-    let browser;
+    if (launch.status === "failed") {
+        return {
+            status: "failed",
+            htmlPath,
+            pngPath,
+            error: launch.error
+        };
+    }
+    const browser = launch.browser;
     try {
-        browser = await playwright.chromium.launch({ headless: true });
-        const page = await browser.newPage({ viewport: { width: 1440, height: 1080 } });
+        const page = await browser.newPage({ viewport: { ...REPORT_VIEWPORT } });
         await page.goto(pathToFileURL(path.resolve(htmlPath)).href, { waitUntil: "load" });
         await page.screenshot({ path: pngPath, fullPage: true });
         await browser.close();
@@ -53,10 +55,11 @@ export async function captureReportScreenshot(htmlPath, pngPath, options) {
         };
     }
     catch (error) {
-        if (browser) {
-            await browser.close().catch(() => undefined);
-        }
-        if (isMissingBrowserRuntime(error)) {
+        await closeBrowserQuietly(browser);
+        // A post-launch failure can still be a missing-browser-runtime symptom (for
+        // example a browser process that dies on first page use), so the same closed
+        // classifier applies here as at launch time.
+        if (isMissingBrowserRuntimeError(error)) {
             return {
                 status: "skipped",
                 htmlPath,
@@ -68,7 +71,7 @@ export async function captureReportScreenshot(htmlPath, pngPath, options) {
             status: "failed",
             htmlPath,
             pngPath,
-            error: error instanceof Error ? error.message : String(error)
+            error: errorMessage(error)
         };
     }
 }

package/dist/src/tutorial/index.js

@@ -0,0 +1,17 @@
+export * from "./types.js";
+export * from "./scenarioValidation.js";
+export * from "./targetContractValidation.js";
+export * from "./loadTutorialContracts.js";
+export * from "./tutorialPaths.js";
+export * from "./tutorialLocators.js";
+export * from "./tutorialActions.js";
+export * from "./tutorialPointerGeometry.js";
+export * from "./tutorialAssertions.js";
+export * from "./tutorialCursor.js";
+export * from "./tutorialOverlay.js";
+export * from "./tutorialArtifacts.js";
+export * from "./subtitleWriter.js";
+export * from "./markdownTutorialWriter.js";
+export * from "./tutorialManifest.js";
+export * from "./tutorialSession.js";
+export * from "./runTutorial.js";

package/dist/src/tutorial/loadTutorialContracts.js

@@ -0,0 +1,60 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { validateTutorialScenario } from "./scenarioValidation.js";
+import { validateTutorialTargetContract } from "./targetContractValidation.js";
+/**
+ * Contract loading follows the v0.4.6 invocation-path rule: an absolute path is
+ * used as supplied, a relative path resolves against invocationCwd -- never
+ * against packageRoot, workspaceRoot or the current process directory.
+ */
+export function resolveInvocationPath(invocationCwd, suppliedPath) {
+    return path.isAbsolute(suppliedPath) ? path.resolve(suppliedPath) : path.resolve(invocationCwd, suppliedPath);
+}
+export async function loadTutorialScenario(invocationCwd, suppliedPath) {
+    const scenarioPath = resolveInvocationPath(invocationCwd, suppliedPath);
+    const parsed = await readJsonFile(scenarioPath, "Tutorial scenario");
+    if (!parsed.ok) {
+        return { ok: false, errors: parsed.errors };
+    }
+    const validated = validateTutorialScenario(parsed.value, scenarioPath);
+    if (!validated.ok) {
+        return { ok: false, errors: validated.errors };
+    }
+    return { ok: true, value: { scenario: validated.value, scenarioPath } };
+}
+export async function loadTutorialTargetContract(invocationCwd, suppliedPath) {
+    const targetContractPath = resolveInvocationPath(invocationCwd, suppliedPath);
+    const parsed = await readJsonFile(targetContractPath, "Tutorial target contract");
+    if (!parsed.ok) {
+        return { ok: false, errors: parsed.errors };
+    }
+    const validated = validateTutorialTargetContract(parsed.value, targetContractPath);
+    if (!validated.ok) {
+        return { ok: false, errors: validated.errors };
+    }
+    return {
+        ok: true,
+        value: {
+            targetContract: validated.value,
+            targetContractPath,
+            contractRoot: path.dirname(targetContractPath)
+        }
+    };
+}
+async function readJsonFile(filePath, label) {
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { ok: false, errors: [`${label} could not be read: ${filePath} (${reason})`] };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { ok: false, errors: [`${label} is not valid JSON: ${filePath} (${reason})`] };
+    }
+}

package/dist/src/tutorial/markdownTutorialWriter.js

@@ -0,0 +1,53 @@
+export function renderTutorialMarkdown(options) {
+    const { scenario } = options;
+    const stepById = new Map(scenario.steps.map((step) => [step.id, step]));
+    const screenshotById = new Map(options.screenshots.filter((record) => record.id !== undefined).map((record) => [record.id, record]));
+    const lines = [];
+    lines.push(`# ${scenario.title}`);
+    if (scenario.description !== undefined && scenario.description.trim().length > 0) {
+        lines.push("");
+        lines.push(scenario.description.trim());
+    }
+    let position = 0;
+    for (const stepResult of options.steps) {
+        // A not-run step never happened, so it is not presented as part of the
+        // tutorial at all.
+        if (stepResult.status === "not-run") {
+            continue;
+        }
+        const step = stepById.get(stepResult.id);
+        if (!step) {
+            continue;
+        }
+        position += 1;
+        lines.push("");
+        lines.push(`## Step ${position}: ${step.id}`);
+        lines.push("");
+        lines.push(step.narration.trim());
+        if (stepResult.status === "failed") {
+            lines.push("");
+            // Stated plainly from the run result; no troubleshooting advice is invented.
+            lines.push(`**This step failed during execution.** ${stepResult.error ?? ""}`.trim());
+        }
+        const screenshotId = step.screenshot?.id;
+        if (screenshotId !== undefined) {
+            const record = screenshotById.get(screenshotId);
+            if (record?.status === "written" && record.path !== undefined) {
+                lines.push("");
+                lines.push(`![${step.id}](${toMarkdownScreenshotLink(record.path)})`);
+            }
+        }
+    }
+    lines.push("");
+    return `${lines.join("\n")}`;
+}
+/**
+ * tutorial.md lives in `artifacts/` and screenshots live in `screenshots/`, both
+ * directly beneath runRoot, so a run-root-relative screenshot path becomes a
+ * `../`-prefixed sibling link. POSIX separators keep the document portable; an
+ * absolute machine path is never written.
+ */
+export function toMarkdownScreenshotLink(runRelativePosixPath) {
+    const normalized = runRelativePosixPath.replace(/\\/g, "/").replace(/^\/+/, "");
+    return `../${normalized}`;
+}