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

package/dist/src/tutorial/types.js

@@ -0,0 +1,48 @@
+/**
+ * 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_ACTION_TYPES = [
+    "goto",
+    "click",
+    "fill",
+    "press",
+    "hover",
+    "drag",
+    "wait-for"
+];
+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.`);
+        }
+    }
+}

package/examples/tutorial-browser/index.html

@@ -0,0 +1,47 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Tutorial Fixture</title>
+    <style>
+      body { font: 16px/1.5 system-ui, sans-serif; margin: 0; padding: 24px; background: #f6f7f9; color: #111; }
+      h1 { margin: 0 0 16px; font-size: 28px; }
+      .panel { background: #fff; border: 1px solid #d8dbe0; border-radius: 8px; padding: 16px; margin-bottom: 16px; }
+      .row { display: flex; gap: 16px; align-items: flex-start; }
+      .col { flex: 1; }
+      button { font: inherit; padding: 8px 16px; border-radius: 6px; border: 1px solid #5a6270; background: #fff; cursor: pointer; }
+      button:hover { background: #eef1f5; }
+      input { font: inherit; padding: 8px; border: 1px solid #b8bec8; border-radius: 6px; width: 100%; box-sizing: border-box; }
+      .dropzone { min-height: 72px; border: 2px dashed #9aa3af; border-radius: 8px; padding: 12px; }
+      .card { background: #dde7ff; border: 1px solid #5f7fd6; border-radius: 6px; padding: 10px; width: 140px; }
+      .hidden { display: none; }
+      #status-banner { padding: 10px; border-radius: 6px; background: #e8f5e9; border: 1px solid #66bb6a; }
+    </style>
+  </head>
+  <body>
+    <h1 id="page-title">Tutorial Fixture</h1>
+    <div class="panel"><p id="intro-text">Welcome to the generic tutorial fixture.</p><button id="primary-action" data-testid="primary-action" data-state="idle">Activate</button> <span id="activation-count" data-testid="activation-count">0</span></div>
+    <div class="panel"><label for="name-field">Your name</label><input id="name-field" data-testid="name-field" aria-label="Your name" /><p id="greeting" data-testid="greeting"></p></div>
+    <div class="panel"><button id="hover-target" data-testid="hover-target">Hover me</button><p id="hover-readout" data-testid="hover-readout">not hovered</p></div>
+    <div class="panel row"><div class="col"><div id="drag-card" data-testid="drag-card" class="card" draggable="true">Draggable card</div></div><div class="col"><div id="drop-zone" data-testid="drop-zone" class="dropzone">Drop target</div></div></div>
+    <div class="panel"><div id="status-banner" data-testid="status-banner" class="hidden">Delayed banner is now visible</div></div>
+    <script>
+      (() => {
+        let activations = 0;
+        const primary = document.getElementById("primary-action");
+        primary.addEventListener("click", () => { activations += 1; document.getElementById("activation-count").textContent = String(activations); primary.setAttribute("data-state", "activated"); });
+        const nameField = document.getElementById("name-field");
+        const greeting = document.getElementById("greeting");
+        nameField.addEventListener("input", () => { greeting.textContent = nameField.value ? `Hello, ${nameField.value}` : ""; });
+        nameField.addEventListener("keydown", event => { if (event.key === "Enter") greeting.textContent = `Submitted: ${nameField.value}`; });
+        document.getElementById("hover-target").addEventListener("mouseenter", () => { document.getElementById("hover-readout").textContent = "hovered"; });
+        const dragCard = document.getElementById("drag-card");
+        const dropZone = document.getElementById("drop-zone");
+        dragCard.addEventListener("dragstart", event => event.dataTransfer.setData("text/plain", "drag-card"));
+        dropZone.addEventListener("dragover", event => event.preventDefault());
+        dropZone.addEventListener("drop", event => { event.preventDefault(); dropZone.textContent = "Dropped"; dropZone.setAttribute("data-dropped", "true"); });
+        window.setTimeout(() => document.getElementById("status-banner").classList.remove("hidden"), 300);
+      })();
+    </script>
+  </body>
+</html>

package/examples/tutorial-browser/prepare.mjs

@@ -0,0 +1,14 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const sourceRoot = path.dirname(fileURLToPath(import.meta.url));
+const targetRoot = process.argv[2];
+if (!targetRoot) {
+  console.error("prepare requires a target root argument");
+  process.exit(2);
+}
+fs.mkdirSync(path.join(targetRoot, "app"), { recursive: true });
+fs.mkdirSync(path.join(targetRoot, "out"), { recursive: true });
+for (const file of ["index.html", "server.mjs"]) fs.copyFileSync(path.join(sourceRoot, file), path.join(targetRoot, "app", file));
+fs.writeFileSync(path.join(targetRoot, "out", "report.json"), JSON.stringify({ prepared: true, counts: { widgets: 3 } }, null, 2), "utf8");

package/examples/tutorial-browser/scenario.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": "1.0.0",
+  "id": "lab-browser-fixture",
+  "title": "Lab browser fixture tutorial",
+  "description": "A generic, lab-owned tutorial that exercises browser actions, locators, assertions and visual declarations against a local static fixture app.",
+  "targetId": "lab-browser-fixture",
+  "browser": { "viewport": { "width": 1024, "height": 768 } },
+  "steps": [
+    { "id": "open-app", "narration": "Open the fixture application in the browser.", "action": { "type": "goto", "path": "/", "waitUntil": "load" }, "highlight": { "kind": "css", "selector": "#page-title" }, "callout": { "text": "This is the fixture application.", "locator": { "kind": "css", "selector": "#page-title" }, "placement": "bottom" }, "screenshot": { "id": "app-open" }, "assertions": [ { "type": "url-path-equals", "expected": "/" }, { "type": "element-visible", "locator": { "kind": "role", "role": "heading", "name": "Tutorial Fixture" } }, { "type": "text-equals", "locator": { "kind": "css", "selector": "#page-title" }, "expected": "Tutorial Fixture" }, { "type": "file-exists", "path": "out/report.json" }, { "type": "json-file-equals", "path": "out/report.json", "pointer": "/counts/widgets", "expected": 3 }, { "type": "http-json-equals", "path": "/api/status", "pointer": "/ok", "expected": true } ] },
+    { "id": "activate", "narration": "Click the primary action button to activate the panel.", "action": { "type": "click", "locator": { "kind": "test-id", "testId": "primary-action" } }, "highlight": { "kind": "test-id", "testId": "primary-action" }, "callout": { "text": "Clicking here activates the panel.", "placement": "auto", "locator": { "kind": "test-id", "testId": "primary-action" } }, "screenshot": { "id": "activated" }, "assertions": [ { "type": "text-equals", "locator": { "kind": "test-id", "testId": "activation-count" }, "expected": "1" }, { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "primary-action" }, "name": "data-state", "expected": "activated" } ] },
+    { "id": "fill-name", "narration": "Type a name into the form field.", "action": { "type": "fill", "locator": { "kind": "test-id", "testId": "name-field" }, "value": "Ada" }, "assertions": [ { "type": "text-contains", "locator": { "kind": "test-id", "testId": "greeting" }, "expected": "Hello, Ada" } ] },
+    { "id": "submit-name", "narration": "Press Enter to submit the name.", "action": { "type": "press", "locator": { "kind": "test-id", "testId": "name-field" }, "key": "Enter" }, "screenshot": { "id": "submitted" }, "assertions": [ { "type": "text-contains", "locator": { "kind": "test-id", "testId": "greeting" }, "expected": "Submitted: Ada" } ] },
+    { "id": "hover-button", "narration": "Hover the secondary button to reveal its state.", "action": { "type": "hover", "locator": { "kind": "test-id", "testId": "hover-target" } }, "assertions": [ { "type": "text-equals", "locator": { "kind": "test-id", "testId": "hover-readout" }, "expected": "hovered" } ] },
+    { "id": "drag-card", "narration": "Drag the card onto the drop target.", "action": { "type": "drag", "source": { "kind": "test-id", "testId": "drag-card" }, "target": { "kind": "test-id", "testId": "drop-zone" } }, "highlight": { "kind": "test-id", "testId": "drop-zone" }, "screenshot": { "id": "dropped" }, "assertions": [ { "type": "attribute-equals", "locator": { "kind": "test-id", "testId": "drop-zone" }, "name": "data-dropped", "expected": "true" } ] },
+    { "id": "wait-banner", "narration": "Wait for the delayed status banner to appear.", "action": { "type": "wait-for", "locator": { "kind": "text", "text": "Delayed banner is now visible" }, "state": "visible", "timeoutMs": 5000 }, "callout": { "text": "The banner appears after a short delay." }, "screenshot": { "id": "banner-visible" }, "assertions": [ { "type": "element-visible", "locator": { "kind": "test-id", "testId": "status-banner" } } ] }
+  ]
+}

package/examples/tutorial-browser/server.mjs

@@ -0,0 +1,14 @@
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.dirname(fileURLToPath(import.meta.url));
+const port = Number(process.env.TUTORIAL_FIXTURE_PORT || 0);
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+  if (url.pathname === "/api/status") { res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: true, widgets: 3 })); return; }
+  const filePath = url.pathname === "/" ? path.join(root, "index.html") : path.join(root, url.pathname);
+  fs.readFile(filePath, (error, contents) => { if (error) { res.writeHead(404); res.end("not found"); return; } res.writeHead(200, { "content-type": filePath.endsWith(".html") ? "text/html" : "application/octet-stream" }); res.end(contents); });
+});
+server.listen(port, "127.0.0.1", () => console.log("tutorial fixture listening on " + server.address().port));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dailephd/my-dev-kit-lab",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "type": "module",
   "description": "Evidence, benchmark, and evaluation companion for my-dev-kit.",
   "bin": {
@@ -13,7 +13,8 @@
     "dist/src/",
     "benchmarks/",
     "docs/METRICS.md",
-    "examples/token-savings-cases.json"
+    "examples/token-savings-cases.json",
+    "examples/tutorial-browser/"
   ],
   "repository": {
     "type": "git",
@@ -79,17 +80,20 @@
     "security:codeql": "tsx scripts/security/runCodeql.ts",
     "security:semgrep": "tsx scripts/security/runSemgrep.ts",
     "test:security": "vitest run tests/security/",
+    "test:tutorial-browser": "vitest run tests/integration/tutorialRealBrowser.spec.ts",
     "test:fuzz:smoke": "tsx scripts/security/runFuzzSmoke.ts",
     "security:validate": "tsx scripts/security/validate.ts",
     "audit": "tsx scripts/audits/runAudit.ts",
     "report:context-integrity-smoke": "tsx scripts/report-context-integrity-smoke.ts"
   },
+  "dependencies": {
+    "playwright": "1.60.0"
+  },
   "devDependencies": {
     "@types/node": "^24.0.0",
-    "playwright": "^1.54.1",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   },
   "overrides": {
     "vite": "7.3.6"