Skip to content

LocalJam v2026.09.117

Choose a tag to compare

View all tags
@github-actions github-actions released this 23 Sep 04:02
Immutable release. Only release title and notes can be modified.
v2026.09.117
484cd18

LocalJam v2026.09.117

Live Deployment & App Access

Commit Details

Subject: feat(scripts): add zero-dependency headless visual artifact capture runner
Date: 2026-09-22 21:01:54 -0700

Commit Message

Technical Rationale & Capabilities:

  • Provide an automated, zero-dependency visual capture runner utilizing Node.js 22
    built-in modules (node:child_process, node:http, node:fs, node:path, node:os).
  • Implement a lightweight, native WebSocket Chrome DevTools Protocol (CDP) client
    (Page, DOM, Runtime, Emulation) without third-party frameworks like Puppeteer.
  • Host application on an ephemeral HTTP server bound to loopback with automatic port
    allocation (port 0) and graceful teardown.
  • Standardize multi-viewport snapshot generation via predefined viewport presets
    (desktop-1280x800 at 1.0x DPR, mobile-390x844 at 3.0x DPR).
  • Add "capture" npm script to package.json (node scripts/capture-visual.js).

Root Cause Analysis (Headless Chrome Execution Constraints):

  1. Headless Viz Compositor Crash Loop: In headless containerized Linux environments
    lacking physical GPUs or X11/Wayland display servers, Chrome's hardware rasterizer
    crashes repeatedly during surface allocation. Remediated by enforcing CPU-based
    rasterization via ANGLE SwiftShader flags:
    --use-gl=angle --use-angle=swiftshader --enable-unsafe-swiftshader.
  2. Crashpad Initialization Failure: Environments where $HOME is mounted read-only cause
    Chrome Crashpad handler to crash with EROFS when attempting to create crash metrics.
    Remediated by redirecting user data and crash dumps to isolated temporary directories
    under TMPDIR via --user-data-dir and --crash-dumps-dir.
  3. Container Sandboxing Constraints: Running inside unprivileged container namespaces
    causes zygote initialization failures and POSIX shared memory exhaustion. Remediated
    with --no-sandbox and --disable-dev-shm-usage.
  4. Chrome Browser Cloud Management (CBCM) Enrollment Timeout: Managed workstation
    profiles hang attempting CBCM enrollment over the network. Remediated by passing
    --disable-cloud-management and injecting an empty enrollment token file in the
    ephemeral user data directory.

Security Controls:

  • Validate all user-supplied identifiers (feature, scope, state, phase) against strict
    alphanumeric kebab-case patterns (^[a-z0-9]+(-[a-z0-9]+)*$).
  • Enforce canonical path containment (path.resolve) to guarantee generated artifact
    targets are strictly confined within ./docs/artifacts/visual/, preventing directory
    traversal vulnerabilities.

Verification:

  • Added 21 automated unit tests in test/scripts/capture-visual.test.js covering CLI parsing,
    identifier validation, canonical path containment, ephemeral server lifecycle,
    DevTools port extraction, and fast-fail process monitoring.
  • Ran node --test test/scripts/capture-visual.test.js: all 21 unit tests passing.
  • Ran node --test: all 446 repository unit tests passing across 11 suites.
Assets 4
Loading