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

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to my-dev-kit-lab are documented here.
 
+## [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
+
+Installed-package CLI and runtime-boundary correction. `@dailephd/my-dev-kit-lab` now ships a supported, cross-platform installed CLI (`my-dev-kit-lab`) alongside the existing contributor npm scripts.
+
+- Added a compiled, cross-platform installed CLI router (`dist/scripts/cli.js`, `src/cli/runLabCli.ts`) exposing `my-dev-kit-lab --help`/`--version`, `security validate`, `audit`, the `experiment` family (`list`/`describe`/`run`/`controlled`), `report render`, `plots generate`, `gallery build`, and `demo final`, plus the historical direct final-demo invocation form for backward compatibility. A global `--workspace <path>` option is supported before any subcommand.
+- Added a `LabExecutionContext` runtime foundation (`src/runtime/`) distinguishing `invocationCwd`, read-only `packageRoot` (discovered independent of `process.cwd()`), writable `workspaceRoot` (default `<home>/.my-dev-kit-lab`, overridable with `--workspace`), `resourceRoot`, and the separately resolved inspected target root, plus cwd-independent, containment-checked package-resource resolution.
+- `security validate`, `audit`, and `experiment` npm scripts now delegate to shared `src/commands/` owners also used by the installed CLI, so both surfaces run the same implementation. Installed `audit`/`security validate` default implicit report output under the writable workspace instead of the package root; installed `experiment run`'s implicit output is under the workspace's `lab-output/experiments/` tree. Explicit output paths and all target-resolution semantics are unchanged.
+- Added a permanent packed-tarball installation/execution acceptance gate (`npm run verify:packed-package`): builds, runs a real `npm pack`, installs the exact tarball into a clean temporary consumer project, executes the installed binary, and verifies default/explicit workspace output and target/installed-package immutability via recursive SHA-256 snapshot comparison.
+- Fixed an installed-runtime defect the acceptance gate surfaced: the TypeScript/JavaScript audit source-facts analyzer imported the `typescript` devDependency eagerly at module load, so even `--help` required it in a clean install; it now loads lazily, only when a source file is actually analyzed. Detector output is unchanged.
+- Reconciled the npm package `files` allowlist against proven installed-runtime requirements: narrowed `dist/scripts/` to the two files the installed CLI and legacy bin target need, narrowed `examples/` to the one file an installed command reads by default, and removed `tests/fixtures/` (developer/test-only, not read by any installed command). `benchmarks/` and `docs/METRICS.md` remain packaged.
+- Raised `engines.node` to `>=24`. Standardized GitHub Actions CI on Node `24` and `latest` across Ubuntu/macOS/Windows, and switched the pre-release readiness workflow from a hard-coded Node version to Node `latest`; both workflows run the packed-package acceptance gate.
+- Resolved a transitive devDependency vulnerability (nanoid, GHSA-2v37-7h3g-55p8) via a lockfile-only update; the published runtime dependency tree was unaffected throughout.
+- No security check, security verdict rule, audit detector, Android behavior, experiment scoring, report schema, or existing CLI syntax changed.
+
 ## [0.4.5] - 2026-08-01
 
 Context-integrity validation for the published my-dev-kit v1.10.4 and my-dev-kit-orchestrator v1.2.3 contracts.
@@ -24,7 +49,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,9 @@ 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.5 (context-integrity validation), 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 published release is v0.4.7 (declarative browser tutorial and video automation). It adds bounded browser scenarios, persistent tutorial sessions, synchronized runtime artifacts, and a packaged generic example while preserving product-specific demo ownership outside this repository. 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.
 
 ## Current capabilities
 
@@ -13,11 +15,48 @@ The latest published release is v0.4.5 (context-integrity validation), compatibl
 - **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. 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.
 
-## Quickstart
+## Installed CLI
+
+Installing or invoking the package (for example via `npm install -g @dailephd/my-dev-kit-lab` or `npx @dailephd/my-dev-kit-lab@<version>`) exposes one `my-dev-kit-lab` binary. Users do not need to clone this repository to use these commands. The installed CLI requires Node `>=24`.
+
+```
+my-dev-kit-lab --help
+my-dev-kit-lab --version
+
+my-dev-kit-lab security validate [options]
+my-dev-kit-lab audit [options]
+
+my-dev-kit-lab experiment list
+my-dev-kit-lab experiment describe --experiment <id>
+my-dev-kit-lab experiment run --experiment <id> [options]
+my-dev-kit-lab experiment controlled [options]
+
+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.
+
+The historical direct final-demo invocation form — the same flags `demo final` accepts, without the `demo final` prefix — continues to work for backward compatibility.
+
+Low-level developer helpers (`security:deps`, `security:package`, `security:codeql`, `security:semgrep`, fuzz smoke, visualization demos, build/test/verify) are not part of the installed CLI. They remain source-checkout contributor workflows; see below.
+
+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.
 
 ### Install
 
@@ -169,12 +208,13 @@ 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 adds 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.
 
 ---
 
 ## Security validation
 
-`npm run security:validate` is the standalone security-validation command. It checks local CLI/package boundaries and can inspect another local project with `--target <path>`. The generic audit command can reuse those results through `--types security`, but it does not replace the standalone validator or its reports.
+`npm run security:validate` (contributor/source-checkout) and `my-dev-kit-lab security validate` (installed CLI) both call the same standalone security-validation command owner. It checks local CLI/package boundaries and can inspect another local project with `--target <path>`. The generic audit command can reuse those results through `--types security`, but it does not replace the standalone validator or its reports.
 
 Android validation uses `--profile android`. Its default path is static and non-destructive: it starts zero Gradle processes, zero external tools, and zero network operations. Only confirmed `SecurityFinding` records can become audit issues; Android `CandidateEvidence` remains review-only evidence.
 

package/dist/scripts/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runLabCli } from "../src/cli/index.js";
+try {
+    process.exitCode = await runLabCli(process.argv.slice(2));
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/dist/src/audits/core/typescriptJavaScriptAnalyzer.js

@@ -1,4 +1,3 @@
-import ts from "typescript";
 // ---------------------------------------------------------------------------
 // v0.3.1 Batch 3 -- TypeScript/JavaScript source analyzer.
 //
@@ -36,7 +35,25 @@ export const TYPESCRIPT_JAVASCRIPT_ANALYZER = {
     supportedExtensions: SUPPORTED_EXTENSIONS,
     analyzeFile,
 };
-function analyzeFile(input) {
+// v0.4.6 Batch 5 -- the `typescript` package is a devDependency, not a
+// runtime dependency: an installed my-dev-kit-lab consumer does not have it.
+// The compiler API is loaded lazily (once, memoized) only when a file is
+// actually analyzed, rather than imported at module scope, so merely
+// loading this module (which happens on every CLI invocation, since the
+// language analyzer registry is wired in unconditionally) never requires
+// `typescript` to be present. Only the *type* import above is needed at the
+// top level -- type-only imports are erased entirely at compile time.
+let cachedTypeScriptModule;
+async function loadTypeScript() {
+    if (!cachedTypeScriptModule) {
+        const imported = await import("typescript");
+        cachedTypeScriptModule =
+            imported.default ??
+                imported;
+    }
+    return cachedTypeScriptModule;
+}
+async function analyzeFile(input) {
     const { relativePath, language, role, content, inventoryEntry } = input;
     if (Buffer.byteLength(content, "utf8") > MAX_ANALYZABLE_BYTES) {
         return {
@@ -61,17 +78,18 @@ function analyzeFile(input) {
             ],
         };
     }
-    const scriptKind = resolveScriptKind(inventoryEntry.extension);
+    const ts = await loadTypeScript();
+    const scriptKind = resolveScriptKind(ts, inventoryEntry.extension);
     const sourceFile = ts.createSourceFile(relativePath, content, ts.ScriptTarget.Latest, true, scriptKind);
-    const diagnostics = getSyntaxDiagnostics(relativePath, sourceFile);
+    const diagnostics = getSyntaxDiagnostics(ts, relativePath, sourceFile);
     const imports = [];
     const exports = [];
     const declarations = [];
     const references = [];
     const lineOf = (node) => sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
     function pushDeclaration(node, name, kind) {
-        const isExported = hasModifier(node, ts.SyntaxKind.ExportKeyword);
-        const isDefault = hasModifier(node, ts.SyntaxKind.DefaultKeyword);
+        const isExported = hasModifier(ts, node, ts.SyntaxKind.ExportKeyword);
+        const isDefault = hasModifier(ts, node, ts.SyntaxKind.DefaultKeyword);
         if (name) {
             declarations.push({ name, kind, exported: isExported, line: lineOf(node) });
         }
@@ -141,7 +159,7 @@ function analyzeFile(input) {
         exports.push({ name, kind: "default", line: lineOf(node) });
     }
     function handleVariableStatement(node) {
-        const isExported = hasModifier(node, ts.SyntaxKind.ExportKeyword);
+        const isExported = hasModifier(ts, node, ts.SyntaxKind.ExportKeyword);
         const isConst = (node.declarationList.flags & ts.NodeFlags.Const) !== 0;
         for (const decl of node.declarationList.declarations) {
             // Destructuring patterns (`const { a, b } = x`) are conservatively
@@ -247,7 +265,7 @@ function analyzeFile(input) {
         diagnostics,
     };
 }
-function resolveScriptKind(extension) {
+function resolveScriptKind(ts, extension) {
     switch (extension) {
         case ".tsx":
             return ts.ScriptKind.TSX;
@@ -264,7 +282,7 @@ function resolveScriptKind(extension) {
             return ts.ScriptKind.TS;
     }
 }
-function hasModifier(node, kind) {
+function hasModifier(ts, node, kind) {
     if (!ts.canHaveModifiers(node))
         return false;
     const modifiers = ts.getModifiers(node);
@@ -280,11 +298,11 @@ function hasModifier(node, kind) {
 // transpileModule() over this repo's own ~375 TS/JS files, which matters
 // because collectSourceFacts.ts calls this analyzer once per eligible file
 // on every audit run (including this repo's own self-audit).
-function getSyntaxDiagnostics(relativePath, sourceFile) {
+function getSyntaxDiagnostics(ts, relativePath, sourceFile) {
     const parseDiagnostics = sourceFile.parseDiagnostics ?? [];
-    return parseDiagnostics.map((diagnostic) => toSourceFactDiagnostic(relativePath, diagnostic));
+    return parseDiagnostics.map((diagnostic) => toSourceFactDiagnostic(ts, relativePath, diagnostic));
 }
-function toSourceFactDiagnostic(relativePath, diagnostic) {
+function toSourceFactDiagnostic(ts, relativePath, diagnostic) {
     const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
     const line = diagnostic.file && diagnostic.start !== undefined
         ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start).line + 1

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 {};