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

package/CHANGELOG.md

@@ -2,7 +2,30 @@
 
 All notable changes to my-dev-kit-lab are documented here.
 
-## [Unreleased]
+## [0.4.8] - 2026-09-19
+
+Locator-anchored pointer gestures for declarative browser tutorials.
+
+- Added `pointer-click` and `pointer-drag` declarative tutorial actions anchored to a single `TutorialLocatorV1` interaction surface.
+- Added normalized fraction coordinates (`coordinateSpace: "fraction"`) with inclusive `[0, 1]` bounds and zero-length pointer-drag rejection.
+- Used real Playwright mouse input (`mouse.move`, `mouse.down`, `mouse.up`) with a fixed 8-step drag movement (`POINTER_DRAG_MOVE_STEPS = 8`) and robust `mouse.up` error cleanup.
+- Preserved existing element-to-element `drag` (`source` and `target` locators via Playwright `dragTo`) and all existing scenario action/assertion behaviors without change.
+- Preserved closed security boundaries: no arbitrary JavaScript, no `page.evaluate` callbacks, no generic DOM event dispatch, no shell actions, and no unanchored page/screen coordinates.
+- Extended the generic real-browser fixture (`examples/tutorial-browser/`) with an interactive SVG pointer surface, verifying pointer clicks, pointer drags, and intermediate pointermove tracking through genuine Chromium.
+- Extended packed-package verification (`npm run verify:packed-package`) to validate and execute the new pointer actions against a clean installed-tarball consumer while maintaining package, target, and example immutability.
+- Validated downstream `my-frontend-observer` compatibility evidence as a read-only compatibility consumer (rectangle, line, arrow, point, and note gestures confirmed expressible without Observer code modifications or runtime dependencies).
+- Kept `TutorialScenarioV1`, `TutorialTargetContractV1`, `TutorialRunResultV1`, and `TutorialManifestV1` schemas at version `1.0.0`.
+
+## [0.4.7] - 2026-09-18
+
+The v0.4.7 implementation adds generic declarative browser tutorial automation while preserving product-specific demo ownership outside this repository.
+
+- Added the shared Playwright browser runtime, managed local process lifecycle/readiness, and persistent tutorial browser sessions.
+- Added strict `TutorialScenarioV1` and `TutorialTargetContractV1` contracts with bounded locators, actions, and assertions.
+- Added tutorial-only cursor/click feedback, highlights, callouts, WebM recording, step screenshots, SRT/VTT subtitles, Markdown, and `tutorial-manifest.json`.
+- Added installed `tutorial validate` and `tutorial run` routes, an exact Playwright runtime dependency, and the packaged generic `examples/tutorial-browser/` fixture.
+- Extended exact packed-tarball clean-consumer acceptance to validate tutorial help/contracts, browser-unavailable behavior without auto-download, real Chromium execution, canonical artifacts, manifest boundaries, workspace routing, and package/example immutability.
+- v0.4.7 was released after cross-platform CI, security validation, code-rot audit, package validation, and packed-package acceptance passed.
 
 ## [0.4.6] - 2026-08-29
 
@@ -40,7 +63,7 @@ Context-integrity validation for the published my-dev-kit v1.10.4 and my-dev-kit
 
 ## [0.4.3] - 2026-07-22
 
-`v0.4.3` (stage-specific bounded-context and workflow-instruction evaluation) is published. `v0.4.4` is the current release. Its complete scope, dependencies, exclusions, and acceptance criteria are preserved in [docs/ROADMAP.md](docs/ROADMAP.md).
+`v0.4.3` (stage-specific bounded-context and workflow-instruction evaluation) was published and was later superseded by `v0.4.4`. Its complete scope, dependencies, exclusions, and acceptance criteria are preserved in [docs/ROADMAP.md](docs/ROADMAP.md).
 
 ### Added
 

package/README.md

@@ -4,7 +4,7 @@ my-dev-kit-lab is the experiment, audit, and evidence companion for [my-dev-kit]
 
 my-dev-kit provides local repository indexing and graph-guided retrieval. my-dev-kit-lab supplies the controlled benchmarks, agent adapters, metrics, security checks, and reports needed to evaluate when that retrieval is useful. Results are evidence for a specific target and configuration; they do not guarantee token savings or security.
 
-The latest published release is v0.4.6 (installed-package CLI and runtime-boundary correction), compatible with published `@dailephd/my-dev-kit@1.10.4` and `@dailephd/my-dev-kit-orchestrator@1.2.3`. See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md).
+The latest release is v0.4.8 (locator-anchored pointer gestures for declarative browser tutorials, adding `pointer-click` and `pointer-drag` using normalized locator-relative fraction positions while existing `drag` remains element-to-element). The v0.4.5 context-integrity evaluation remains intentionally frozen against the published `@dailephd/my-dev-kit@1.10.4` and `@dailephd/my-dev-kit-orchestrator@1.2.3` contracts; those versions are historical validation baselines, not a statement that they are the ecosystem's current releases. See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md).
 
 v0.4.6 adds a supported `my-dev-kit-lab` installed CLI router (`--help`, `--version`, `security validate`, `audit`, the `experiment` family, `report render`, `plots generate`, `gallery build`, `demo final`, and the historical direct final-demo invocation form), a writable lab workspace model kept separate from the installed package and the inspected target, and a permanent packed-tarball installation/execution acceptance gate (`npm run verify:packed-package`). See [docs/ROADMAP.md](docs/ROADMAP.md) and [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) for status detail and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the runtime path model. The "Installed CLI" section below documents the shipped command surface; the source-checkout `npm run` workflow in Quickstart remains available for contributors.
 
@@ -15,6 +15,7 @@ v0.4.6 adds a supported `my-dev-kit-lab` installed CLI router (`--help`, `--vers
 - **Validate CLI/package security:** inspect dependencies, package contents, path and subprocess boundaries, malformed inputs, optional static scanners, and bounded fuzz targets.
 - **Validate Android projects:** run nineteen static checks by default, with Gradle operations, external tools, and network access available only through explicit opt-in flags.
 - **Review evidence:** generate JSON and HTML reports, SVG plots, optional screenshots, visualization demos, and a static gallery.
+- **Generate declarative browser tutorials:** validate and execute bounded local browser scenarios with WebM recording, step screenshots, SRT/VTT subtitles, Markdown, and a tutorial manifest. Locator-anchored pointer gestures (`pointer-click` and `pointer-drag`) operate using normalized fraction coordinates inside a single located surface, while existing `drag` remains element-to-element. Tutorial execution requires a compatible locally installed Chromium; see [docs/COMMANDS.md](docs/COMMANDS.md) and [docs/TUTORIAL.md](docs/TUTORIAL.md) for details.
 - **Evaluate stage-context strategies:** compare the two legacy strategies against six additional bounded stage-context strategies — `architecture-context-only`, `architecture-plus-implementation-refresh`, `architecture-plus-implementation-and-test-refresh`, `full-workflow-library`, `bounded-workflow-instruction-packet`, and `combined-bounded-stage-context` — selected through programmatic configuration, not CLI flags. Each strategy's evidence is reported through bounded `report.json`, `report.html`, and `report.txt` output with an explicit `available`/`unavailable`/`not-applicable` metric-availability model and no composite score, grade, ranking, or winning strategy.
 - **Evaluate the producer-readiness bridge (v0.4.4):** optionally extend `combined-bounded-stage-context` with the frozen my-dev-kit-orchestrator supplemental implementation/test-context packet and retrieval-report documents plus an observed readiness result, all supplied programmatically (there is no CLI flag), to measure owner, allocation, truncation-cause, supplemental/raw agreement, readiness-agreement, and criticality-overlay evidence without reimplementing upstream owner-selection, allocation, producer-parity, or readiness policy.
 - **Evaluate context integrity (v0.4.5):** compare condition-aware producer evidence from my-dev-kit v1.10.4 (role condition coverage, allocation/spillover, required-evidence-loss) against my-dev-kit-orchestrator v1.2.3 run-integrity evidence (run-integrity gate, judge integrity, final-report eligibility, artifact lifecycle state), reporting agreement or contradiction between them rather than re-deriving a verdict. Evaluation runs against a frozen, hash-verified regression fixture pair — a byte-exact real historical failed run and a hand-distilled corrected-replay counterpart representing the same validated contracts — and is programmatic/test-driven only. `npm run report:context-integrity-smoke` renders both fixtures' reports for manual inspection; it takes no arguments and is a developer convenience, not a configurable evaluation CLI.
@@ -39,6 +40,8 @@ my-dev-kit-lab report render [options]
 my-dev-kit-lab plots generate [options]
 my-dev-kit-lab gallery build [options]
 my-dev-kit-lab demo final [options]
+my-dev-kit-lab tutorial validate --scenario <path> [--target-contract <path>] [--json]
+my-dev-kit-lab tutorial run --scenario <path> --target-contract <path> [--out <dir>] [--json]
 ```
 
 A global `--workspace <path>` option, placed before the command, selects the writable lab workspace. The default workspace, used when `--workspace` is omitted, is `<home>/.my-dev-kit-lab`. Generated reports and experiment output are written under the workspace by default, never under the installed package directory or an inspected `--target` project. Explicit output paths (`--out`, and similar flags) keep their existing resolution behavior and are never redirected under the workspace.
@@ -49,6 +52,8 @@ Low-level developer helpers (`security:deps`, `security:package`, `security:code
 
 See [docs/COMMANDS.md](docs/COMMANDS.md) for full command syntax and flags.
 
+Tutorial runs keep the scenario source, disposable target, logs, browser recording, and generated artifacts separate. The canonical generic example is packaged at `examples/tutorial-browser/`; product-specific demo sites and scenarios remain owned by their product repositories.
+
 ## Quickstart (contributor / source-checkout workflow)
 
 The commands in this section run from a cloned repository checkout and are the contributor/development workflow. They are not required to use the installed CLI documented above.
@@ -203,6 +208,8 @@ See [docs/METRICS.md](docs/METRICS.md) for full metric definitions.
 - The published upstream artifacts the stage-context strategies read do not expose considered-but-unselected reads or unnecessary-read evidence; those metrics report `unavailable` rather than zero
 - The v0.4.4 producer-readiness bridge is released. All bridge inputs are programmatic — there is no CLI flag. The coordinated upstream releases my-dev-kit@1.10.3 and orchestrator@1.2.2 were verified published before lab publication.
 - The v0.4.5 context-integrity evaluation is released. It has no CLI flags, no plots/screenshot/gallery integration, and produces no composite score, grade, ranking, or winner. Its corrected-replay fixture is a hand-distilled representation of the validated my-dev-kit v1.10.4 and my-dev-kit-orchestrator v1.2.3 contracts, not a live capture of a complete ten-stage workflow. The orchestrator agreement evidence does not read a literal upstream `promptMode` field; `stageMayRenderNormalPrompt`, derived from structured blocked-stage evidence, is the bounded substitute used instead.
+- v0.4.7 added declarative browser tutorial validation and execution with bounded actions/assertions, persistent Chromium sessions, WebM, screenshots, SRT/VTT, Markdown, and `tutorial-manifest.json`. Chromium is a separate local runtime prerequisite; the package does not download browser binaries automatically. Gallery consumption remains future scope.
+- v0.4.8 added `pointer-click` and `pointer-drag` for normalized fraction positions inside a single located element. Existing `drag` remains element-to-element between source and target locators.
 
 ---
 

package/dist/src/browser/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./playwrightRuntime.js";

package/dist/src/browser/playwrightRuntime.js

@@ -0,0 +1,74 @@
+export const DEFAULT_BROWSER_HEADLESS = true;
+/**
+ * Message fragments that identify a genuinely missing Chromium/browser binary.
+ *
+ * This is an intentionally closed list carried over unchanged from the v0.4.6
+ * screenshot classifier so existing skip/fail behavior is preserved exactly. It
+ * is not a general-purpose error classifier and must not be broadened into one.
+ */
+export const MISSING_BROWSER_RUNTIME_MESSAGE_FRAGMENTS = [
+    "Executable doesn't exist",
+    "browserType.launch",
+    "playwright install",
+    "Failed to launch",
+    "Could not find Chrome",
+    "ENOENT"
+];
+export function isMissingBrowserRuntimeError(error) {
+    const message = errorMessage(error);
+    return MISSING_BROWSER_RUNTIME_MESSAGE_FRAGMENTS.some((fragment) => message.includes(fragment));
+}
+export async function loadPlaywrightModule() {
+    return (await import("playwright"));
+}
+/**
+ * Launches Chromium and classifies the three outcomes callers care about.
+ *
+ * Returns a structured result rather than throwing for the two expected
+ * environment states (module missing, browser binary missing), because every
+ * current and planned consumer has to make its own policy decision about them.
+ * This function owns no consumer-specific status names or warning text.
+ */
+export async function launchChromium(options = {}) {
+    const loadPlaywright = options.loadPlaywright ?? loadPlaywrightModule;
+    const headless = options.headless ?? DEFAULT_BROWSER_HEADLESS;
+    let playwright;
+    try {
+        playwright = await loadPlaywright();
+    }
+    catch (error) {
+        return {
+            status: "unavailable",
+            reason: "playwright-module-unavailable",
+            error: errorMessage(error)
+        };
+    }
+    try {
+        const browser = await playwright.chromium.launch({ headless });
+        return { status: "launched", browser };
+    }
+    catch (error) {
+        if (isMissingBrowserRuntimeError(error)) {
+            return {
+                status: "unavailable",
+                reason: "browser-runtime-unavailable",
+                error: errorMessage(error)
+            };
+        }
+        return { status: "failed", error: errorMessage(error) };
+    }
+}
+/**
+ * Best-effort cleanup shared by every browser consumer. Closing a browser that
+ * is already gone, or whose transport already failed, must never mask the error
+ * the caller is actually reporting.
+ */
+export async function closeBrowserQuietly(browser) {
+    if (!browser) {
+        return;
+    }
+    await browser.close().catch(() => undefined);
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/browser/types.js

@@ -0,0 +1,10 @@
+/**
+ * Minimal structural types for the parts of Playwright this repository actually
+ * uses. They exist so production code and tests can depend on a narrow shape
+ * instead of the full Playwright type surface, and so a fake runtime can be
+ * injected without installing a browser.
+ *
+ * These are deliberately generic: they describe a browser runtime, not report
+ * screenshots and not tutorials.
+ */
+export {};

package/dist/src/cli/help.js

@@ -14,6 +14,8 @@ export function renderTopLevelHelp() {
         "  my-dev-kit-lab [--workspace <path>] report render --experiment <dir> --out <dir> [options]",
         "  my-dev-kit-lab [--workspace <path>] plots generate --experiment <dir> --out <dir>",
         "  my-dev-kit-lab [--workspace <path>] gallery build --out <dir> [options]",
+        "  my-dev-kit-lab tutorial validate --scenario <path> [--target-contract <path>]",
+        "  my-dev-kit-lab [--workspace <path>] tutorial run --scenario <path> --target-contract <path> [options]",
         "  my-dev-kit-lab demo final --cases <path> --out <dir> --kit-command <command> [options]",
         "",
         "Options:",
@@ -32,6 +34,8 @@ export function renderTopLevelHelp() {
         "  report render             Render an experiment report from controlled-experiment artifacts",
         "  plots generate             Generate experiment plot artifacts",
         "  gallery build              Build a gallery manifest/index",
+        "  tutorial validate          Validate a tutorial scenario and optional target contract",
+        "  tutorial run               Run a declarative browser tutorial scenario",
         "  demo final                 Run the full final demo workflow",
         "",
         "Run \"my-dev-kit-lab <command> --help\" (or \"my-dev-kit-lab <family> <command> --help\") for details.",
@@ -298,3 +302,75 @@ export function renderUnknownCommandError(command) {
         "Run \"my-dev-kit-lab --help\" for usage."
     ].join("\n");
 }
+export function renderTutorialHelp() {
+    return [
+        "my-dev-kit-lab tutorial - declarative browser tutorial command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab tutorial validate --scenario <path> [--target-contract <path>] [--json]",
+        "  my-dev-kit-lab [--workspace <path>] tutorial run --scenario <path> --target-contract <path> [options]",
+        "  my-dev-kit-lab tutorial --help",
+        "",
+        "Commands:",
+        "  validate   Validate a tutorial scenario, and optionally a target contract and their",
+        "             declared target identity. Does not start processes or a browser.",
+        "             Run \"my-dev-kit-lab tutorial validate --help\" for details.",
+        "  run        Prepare a disposable target, start its declared processes, and execute a",
+        "             tutorial scenario in a persistent browser session.",
+        "             Run \"my-dev-kit-lab tutorial run --help\" for details."
+    ].join("\n");
+}
+export function renderTutorialValidateHelp() {
+    return [
+        "my-dev-kit-lab tutorial validate - validate tutorial contracts",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab tutorial validate --scenario <path> [--target-contract <path>] [--json]",
+        "",
+        "Required:",
+        "  --scenario <path>           Path to a TutorialScenarioV1 JSON file",
+        "",
+        "Options:",
+        "  --target-contract <path>    Also validate a TutorialTargetContractV1 JSON file and",
+        "                              verify that the scenario targetId matches its id",
+        "  --json                      Print a deterministic JSON report instead of a summary",
+        "",
+        "Relative paths resolve against the directory the command was invoked from.",
+        "This command is read-only: it creates no directories, runs no commands, starts no",
+        "processes, and does not require a browser runtime.",
+        "",
+        "Exit codes:",
+        "  0   Contracts are valid",
+        "  1   Contract validation failed",
+        "  2   Invalid command usage"
+    ].join("\n");
+}
+export function renderTutorialRunHelp() {
+    return [
+        "my-dev-kit-lab tutorial run - run a declarative browser tutorial scenario",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab [--workspace <path>] tutorial run --scenario <path> --target-contract <path> [--out <dir>] [--json]",
+        "",
+        "Required:",
+        "  --scenario <path>           Path to a TutorialScenarioV1 JSON file",
+        "  --target-contract <path>    Path to a TutorialTargetContractV1 JSON file",
+        "",
+        "Options:",
+        "  --out <dir>                 Explicit run directory. An absolute path is used as given;",
+        "                              a relative path resolves against the invocation directory.",
+        "                              When omitted, the run is written to",
+        "                              <workspace>/tutorials/<scenario-id>/<run-id>/",
+        "  --json                      Print the TutorialRunResultV1 JSON instead of a summary",
+        "",
+        "The run prepares a disposable target working copy beneath the run directory, starts the",
+        "processes the target contract declares, waits for each declared local readiness probe,",
+        "then executes every scenario step in one persistent browser page. Process logs are",
+        "written beneath the run directory and are not printed to the terminal.",
+        "",
+        "Exit codes:",
+        "  0   The tutorial run passed",
+        "  1   The invocation was valid but the tutorial did not pass",
+        "  2   Invalid command usage"
+    ].join("\n");
+}

package/dist/src/cli/runLabCli.js

@@ -10,8 +10,10 @@ import { runExperimentRunCommandFromArgs } from "../commands/runExperimentRunCom
 import { runRenderExperimentReportCommand } from "../commands/renderExperimentReportCommand.js";
 import { runGenerateExperimentPlotsCommand } from "../commands/generateExperimentPlotsCommand.js";
 import { runBuildGalleryCommand } from "../commands/buildGalleryCommand.js";
+import { runTutorialValidateCommandFromArgs } from "../commands/runTutorialValidateCommand.js";
+import { runTutorialRunCommandFromArgs } from "../commands/runTutorialRunCommand.js";
 import { createLabExecutionContext, discoverPackageRoot } from "../runtime/index.js";
-import { renderDemoHelp, renderExperimentControlledHelp, renderExperimentDescribeHelp, renderExperimentHelp, renderExperimentListHelp, renderExperimentRunHelp, renderFinalDemoHelp, renderGalleryBuildHelp, renderGalleryHelp, renderPlotsGenerateHelp, renderPlotsHelp, renderReportHelp, renderReportRenderHelp, renderSecurityHelp, renderTopLevelHelp, renderUnknownCommandError } from "./help.js";
+import { renderDemoHelp, renderExperimentControlledHelp, renderExperimentDescribeHelp, renderExperimentHelp, renderExperimentListHelp, renderExperimentRunHelp, renderFinalDemoHelp, renderGalleryBuildHelp, renderGalleryHelp, renderPlotsGenerateHelp, renderPlotsHelp, renderReportHelp, renderReportRenderHelp, renderSecurityHelp, renderTopLevelHelp, renderTutorialHelp, renderTutorialRunHelp, renderTutorialValidateHelp, renderUnknownCommandError } from "./help.js";
 export const CLI_USAGE_EXIT_CODE = 2;
 /**
  * Recognized legacy final-demo flag tokens (mirrors parseRunFinalDemoArgs in
@@ -80,6 +82,9 @@ export async function runLabCli(argv, options = {}) {
     if (command === "gallery") {
         return runGalleryFamily(rest, writers);
     }
+    if (command === "tutorial") {
+        return runTutorialFamily(rest, writers, context);
+    }
     if (command === "demo") {
         return runDemoCommand(rest, writers);
     }
@@ -202,6 +207,29 @@ async function runPlotsFamily(argv, writers) {
     writers.stderr(renderUnknownCommandError(`plots ${subcommand}`));
     return CLI_USAGE_EXIT_CODE;
 }
+async function runTutorialFamily(argv, writers, context) {
+    const [subcommand, ...rest] = argv;
+    if (argv.length === 0 || subcommand === "--help" || subcommand === "-h") {
+        writers.stdout(renderTutorialHelp());
+        return 0;
+    }
+    if (subcommand === "validate") {
+        if (rest[0] === "--help" || rest[0] === "-h") {
+            writers.stdout(renderTutorialValidateHelp());
+            return 0;
+        }
+        return runTutorialValidateCommandFromArgs(rest, { context });
+    }
+    if (subcommand === "run") {
+        if (rest[0] === "--help" || rest[0] === "-h") {
+            writers.stdout(renderTutorialRunHelp());
+            return 0;
+        }
+        return runTutorialRunCommandFromArgs(rest, { context });
+    }
+    writers.stderr(renderUnknownCommandError(`tutorial ${subcommand}`));
+    return CLI_USAGE_EXIT_CODE;
+}
 async function runGalleryFamily(argv, writers) {
     const [subcommand, ...rest] = argv;
     if (argv.length === 0 || subcommand === "--help" || subcommand === "-h") {

package/dist/src/commands/runTutorialRunCommand.js

@@ -0,0 +1,170 @@
+import { createLabExecutionContext } from "../runtime/index.js";
+import { runTutorial } from "../tutorial/index.js";
+// ---------------------------------------------------------------------------
+// v0.4.7 Batch 2 -- tutorial run command owner.
+//
+// A thin adapter: parse a closed option set, resolve execution roots through
+// LabExecutionContext, delegate to runTutorial(), render a summary, map the run
+// status to an exit code. No tutorial semantics live here.
+// ---------------------------------------------------------------------------
+export const TUTORIAL_CLI_USAGE_EXIT_CODE = 2;
+const RUN_USAGE = "Usage: my-dev-kit-lab tutorial run --scenario <path> --target-contract <path> [--out <dir>] [--json]";
+export async function runTutorialRunCommandFromArgs(argv, options = {}) {
+    const writers = options.writers ?? {
+        stdout: (message) => console.log(message),
+        stderr: (message) => console.error(message)
+    };
+    const parsed = parseRunArgs(argv);
+    if (!parsed.ok) {
+        writers.stderr(parsed.error);
+        return TUTORIAL_CLI_USAGE_EXIT_CODE;
+    }
+    const context = options.context ?? createLabExecutionContext();
+    const execute = options.runTutorialImpl ?? runTutorial;
+    const result = await execute({
+        scenarioPath: parsed.scenarioPath,
+        targetContractPath: parsed.targetContractPath,
+        context,
+        ...(parsed.outDir !== undefined ? { outDir: parsed.outDir } : {}),
+        ...(options.launchBrowser ? { launchBrowser: options.launchBrowser } : {}),
+        ...(options.generateRunId ? { generateRunId: options.generateRunId } : {})
+    });
+    if (parsed.json) {
+        writers.stdout(JSON.stringify(result, null, 2));
+    }
+    else {
+        writers.stdout(renderRunSummary(result));
+    }
+    return result.status === "passed" ? 0 : 1;
+}
+/**
+ * Concise by design: identity, location, outcome, and the first thing that went
+ * wrong. Child-process logs are written to the run's logs directory and are
+ * never dumped to the terminal automatically.
+ */
+function renderRunSummary(result) {
+    const lines = [];
+    lines.push(`Scenario ID: ${result.scenarioId ?? "(not loaded)"}`);
+    lines.push(`Target ID: ${result.targetId ?? "(not loaded)"}`);
+    lines.push(`Run ID: ${result.runId ?? "(not started)"}`);
+    lines.push(`Run root: ${result.paths?.runRoot ?? "(not created)"}`);
+    lines.push(`Status: ${result.status}`);
+    lines.push(`Duration: ${result.durationMs}ms`);
+    const stepCounts = summarizeSteps(result);
+    if (result.steps.length > 0) {
+        lines.push(`Steps: ${result.steps.length} (passed ${stepCounts.passed}, failed ${stepCounts.failed}, not-run ${stepCounts.notRun})`);
+    }
+    const failedStep = result.steps.find((step) => step.status === "failed");
+    if (failedStep) {
+        lines.push(`Failed step: ${failedStep.id}`);
+    }
+    lines.push(...renderArtifactLines(result));
+    if (result.error) {
+        lines.push(`Error: ${result.error}`);
+    }
+    for (const warning of result.warnings) {
+        lines.push(`Warning: ${warning}`);
+    }
+    for (const cleanupError of result.cleanupErrors) {
+        lines.push(`Cleanup error: ${cleanupError}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * One line per canonical artifact that was actually written, plus a screenshot
+ * count. Failed or skipped artifacts are named so a reader sees why, but the
+ * manifest itself is never dumped here -- that is what --json is for.
+ */
+function renderArtifactLines(result) {
+    const artifacts = result.artifacts;
+    const lines = [];
+    const named = [
+        ["Video", artifacts.video],
+        ["SRT", artifacts.srt],
+        ["VTT", artifacts.vtt],
+        ["Markdown", artifacts.markdown],
+        ["Manifest", artifacts.manifest]
+    ];
+    const written = named.filter(([, record]) => record?.status === "written");
+    for (const [label, record] of written) {
+        lines.push(`${label}: ${record.path ?? ""}`);
+    }
+    const writtenScreenshots = artifacts.screenshots.filter((record) => record.status === "written");
+    if (artifacts.screenshots.length > 0) {
+        lines.push(`Screenshots: ${writtenScreenshots.length} of ${artifacts.screenshots.length} written`);
+    }
+    for (const [label, record] of named) {
+        if (record && record.status !== "written") {
+            lines.push(`${label} artifact ${record.status}: ${record.error ?? "no detail"}`);
+        }
+    }
+    for (const record of artifacts.screenshots) {
+        if (record.status !== "written") {
+            lines.push(`Screenshot ${record.id ?? "?"} ${record.status}: ${record.error ?? "no detail"}`);
+        }
+    }
+    return lines;
+}
+function summarizeSteps(result) {
+    let passed = 0;
+    let failed = 0;
+    let notRun = 0;
+    for (const step of result.steps) {
+        if (step.status === "passed")
+            passed += 1;
+        else if (step.status === "failed")
+            failed += 1;
+        else
+            notRun += 1;
+    }
+    return { passed, failed, notRun };
+}
+function parseRunArgs(argv) {
+    let scenarioPath;
+    let targetContractPath;
+    let outDir;
+    let json = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--scenario") {
+            const value = argv[++index];
+            if (value === undefined) {
+                return { ok: false, error: `Missing value for --scenario. ${RUN_USAGE}` };
+            }
+            scenarioPath = value;
+        }
+        else if (arg === "--target-contract") {
+            const value = argv[++index];
+            if (value === undefined) {
+                return { ok: false, error: `Missing value for --target-contract. ${RUN_USAGE}` };
+            }
+            targetContractPath = value;
+        }
+        else if (arg === "--out") {
+            const value = argv[++index];
+            if (value === undefined) {
+                return { ok: false, error: `Missing value for --out. ${RUN_USAGE}` };
+            }
+            outDir = value;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else {
+            return { ok: false, error: `Unknown argument for "tutorial run": ${arg}. ${RUN_USAGE}` };
+        }
+    }
+    if (scenarioPath === undefined) {
+        return { ok: false, error: `Missing required --scenario. ${RUN_USAGE}` };
+    }
+    if (targetContractPath === undefined) {
+        return { ok: false, error: `Missing required --target-contract. ${RUN_USAGE}` };
+    }
+    return {
+        ok: true,
+        scenarioPath,
+        targetContractPath,
+        ...(outDir !== undefined ? { outDir } : {}),
+        json
+    };
+}

package/dist/src/commands/runTutorialValidateCommand.js

@@ -0,0 +1,138 @@
+import { createLabExecutionContext } from "../runtime/index.js";
+import { describeTargetIdMismatch, loadTutorialScenario, loadTutorialTargetContract, tutorialTargetIdsMatch } from "../tutorial/index.js";
+// ---------------------------------------------------------------------------
+// v0.4.7 Batch 2 -- tutorial contract validation command owner.
+//
+// Read-only by construction: it loads and validates contracts and nothing else.
+// No run directory is created, no prepare command runs, no process starts and
+// no browser launches, so this route is safe to run anywhere and needs neither
+// Chromium nor a prepared target.
+// ---------------------------------------------------------------------------
+export const TUTORIAL_CLI_USAGE_EXIT_CODE = 2;
+export async function runTutorialValidateCommandFromArgs(argv, options = {}) {
+    const writers = options.writers ?? {
+        stdout: (message) => console.log(message),
+        stderr: (message) => console.error(message)
+    };
+    const parsed = parseValidateArgs(argv);
+    if (!parsed.ok) {
+        writers.stderr(parsed.error);
+        return TUTORIAL_CLI_USAGE_EXIT_CODE;
+    }
+    const context = options.context ?? createLabExecutionContext();
+    const report = { status: "valid", scenarioPath: parsed.scenarioPath, errors: [] };
+    const loadedScenario = await loadTutorialScenario(context.invocationCwd, parsed.scenarioPath);
+    if (!loadedScenario.ok) {
+        report.status = "invalid";
+        report.errors.push(...loadedScenario.errors);
+    }
+    else {
+        report.scenarioPath = loadedScenario.value.scenarioPath;
+        report.scenarioId = loadedScenario.value.scenario.id;
+        report.scenarioTitle = loadedScenario.value.scenario.title;
+        report.targetIdDeclared = loadedScenario.value.scenario.targetId;
+        report.stepCount = loadedScenario.value.scenario.steps.length;
+    }
+    if (parsed.targetContractPath !== undefined) {
+        const loadedTarget = await loadTutorialTargetContract(context.invocationCwd, parsed.targetContractPath);
+        if (!loadedTarget.ok) {
+            report.status = "invalid";
+            report.targetContractPath = parsed.targetContractPath;
+            report.errors.push(...loadedTarget.errors);
+        }
+        else {
+            report.targetContractPath = loadedTarget.value.targetContractPath;
+            report.targetContractId = loadedTarget.value.targetContract.id;
+            report.processCount = loadedTarget.value.targetContract.processes.length;
+            report.applicationUrl = loadedTarget.value.targetContract.applicationUrl;
+            if (loadedScenario.ok) {
+                const matches = tutorialTargetIdsMatch(loadedScenario.value.scenario.targetId, loadedTarget.value.targetContract.id);
+                report.targetIdMatches = matches;
+                if (!matches) {
+                    report.status = "invalid";
+                    report.errors.push(describeTargetIdMismatch(loadedScenario.value.scenario.targetId, loadedTarget.value.targetContract.id));
+                }
+            }
+        }
+    }
+    if (parsed.json) {
+        writers.stdout(JSON.stringify(report, null, 2));
+    }
+    else {
+        writers.stdout(renderValidateSummary(report));
+    }
+    return report.status === "valid" ? 0 : 1;
+}
+function renderValidateSummary(report) {
+    const lines = [];
+    lines.push(`Scenario: ${report.scenarioPath}`);
+    if (report.scenarioId) {
+        lines.push(`Scenario ID: ${report.scenarioId}`);
+        lines.push(`Title: ${report.scenarioTitle ?? ""}`);
+        lines.push(`Declared target ID: ${report.targetIdDeclared ?? ""}`);
+        lines.push(`Steps: ${report.stepCount ?? 0}`);
+    }
+    if (report.targetContractPath) {
+        lines.push(`Target contract: ${report.targetContractPath}`);
+    }
+    if (report.targetContractId) {
+        lines.push(`Target contract ID: ${report.targetContractId}`);
+        lines.push(`Managed processes: ${report.processCount ?? 0}`);
+        lines.push(`Application URL: ${report.applicationUrl ?? ""}`);
+    }
+    lines.push(`Status: ${report.status}`);
+    if (report.errors.length > 0) {
+        lines.push("");
+        lines.push("Errors:");
+        for (const error of report.errors) {
+            lines.push(`  - ${error}`);
+        }
+    }
+    return lines.join("\n");
+}
+function parseValidateArgs(argv) {
+    let scenarioPath;
+    let targetContractPath;
+    let json = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--scenario") {
+            const value = argv[++index];
+            if (value === undefined) {
+                return { ok: false, error: "Missing value for --scenario. Expected a path to a tutorial scenario JSON file." };
+            }
+            scenarioPath = value;
+        }
+        else if (arg === "--target-contract") {
+            const value = argv[++index];
+            if (value === undefined) {
+                return {
+                    ok: false,
+                    error: "Missing value for --target-contract. Expected a path to a tutorial target contract JSON file."
+                };
+            }
+            targetContractPath = value;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else {
+            return {
+                ok: false,
+                error: `Unknown argument for "tutorial validate": ${arg}. Usage: my-dev-kit-lab tutorial validate --scenario <path> [--target-contract <path>] [--json]`
+            };
+        }
+    }
+    if (scenarioPath === undefined) {
+        return {
+            ok: false,
+            error: "Missing required --scenario. Usage: my-dev-kit-lab tutorial validate --scenario <path> [--target-contract <path>] [--json]"
+        };
+    }
+    return {
+        ok: true,
+        scenarioPath,
+        ...(targetContractPath !== undefined ? { targetContractPath } : {}),
+        json
+    };
+}