@stage5/lumine 0.3.14 → 0.3.16

package/lib/sponsor-preview.js

@@ -0,0 +1,271 @@
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { createCdpPipe, findChromeExecutable } from "./build-review.js";
+
+// `lumine sponsor job preview` renders a Workshop job's saved draft from the
+// Twinkle preview origin: the same version URL (with SDK injection and asset
+// rewrites) that the requester's workspace "App preview" frame loads. It runs
+// top-level in headless Chrome, without the Twinkle host page around it, so
+// host-bridged SDK calls (sign-in identity, saves, rewards) are not exercised.
+
+export const DEFAULT_PREVIEW_RENDER_MS = 8_000;
+export const MAX_PREVIEW_RENDER_MS = 30_000;
+const MAX_PREVIEW_LOG_LINES = 200;
+
+export function normalizePreviewRenderMs(value) {
+  if (value === undefined || value === null || value === "") {
+    return DEFAULT_PREVIEW_RENDER_MS;
+  }
+  const parsed = Number(value);
+  if (
+    !Number.isSafeInteger(parsed) ||
+    parsed < 1_000 ||
+    parsed > MAX_PREVIEW_RENDER_MS
+  ) {
+    throw new Error(
+      `--wait-ms for a job preview must be an integer between 1000 and ${MAX_PREVIEW_RENDER_MS}.`,
+    );
+  }
+  return parsed;
+}
+
+// The preview URL carries a short-lived preview credential for the
+// requester's workspace; nothing the CLI prints or stores keeps it.
+export function redactPreviewCredential(value) {
+  // Plain (?buildApiToken=…), percent-encoded (buildApiToken%3D…, as in a
+  // nested URL) and double-encoded (%253D) forms all lose their value.
+  return String(value ?? "").replace(
+    /(buildApiToken(?:=|%3D|%253D))(?:[A-Za-z0-9._~+\/-]|%(?!26|2526|23|2523)[0-9A-Fa-f]{2})+/gi,
+    "$1<redacted>",
+  );
+}
+
+const PAGE_STATE_EXPRESSION = `(() => {
+  const body = document.body;
+  const visible = (el) => {
+    const rect = el.getBoundingClientRect();
+    const style = getComputedStyle(el);
+    return rect.width > 1 && rect.height > 1 && style.display !== 'none' &&
+      style.visibility !== 'hidden' && Number(style.opacity || 1) > 0;
+  };
+  const media = body
+    ? [...body.querySelectorAll('canvas, img, svg, video')].filter(visible).length
+    : 0;
+  const text = body ? String(body.innerText || '').replace(/\\s+/g, ' ').trim() : '';
+  return {
+    readyState: document.readyState,
+    title: document.title || '',
+    textLength: text.length,
+    textSample: text.slice(0, 160),
+    visibleMediaCount: media,
+    elementCount: body ? body.querySelectorAll('*').length : 0
+  };
+})()`;
+
+function remoteArgumentText(argument) {
+  if (Object.hasOwn(argument || {}, "value")) {
+    const value = argument.value;
+    return typeof value === "string" ? value : JSON.stringify(value);
+  }
+  return String(argument?.description || argument?.type || "");
+}
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+async function waitForPageTarget(cdp) {
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    const result = await cdp.send("Target.getTargets");
+    const page = (result.targetInfos || []).find(
+      (target) => target.type === "page",
+    );
+    if (page) return page;
+    await delay(100);
+  }
+  throw new Error("Chrome did not open a page for the job preview.");
+}
+
+export async function renderDraftPreview({
+  url,
+  outputDir,
+  waitMs = DEFAULT_PREVIEW_RENDER_MS,
+  browserPath = "",
+}) {
+  let executable;
+  try {
+    executable = findChromeExecutable(browserPath);
+  } catch (error) {
+    return {
+      ok: false,
+      skipped: true,
+      reason: "browser_not_found",
+      message: String(error?.message || error),
+    };
+  }
+  const profileDir = mkdtempSync(path.join(outputDir, "browser-profile-"));
+  const screenshotPath = path.join(outputDir, "preview.png");
+  const child = spawn(
+    executable,
+    [
+      "--headless=new",
+      "--no-first-run",
+      "--no-default-browser-check",
+      "--disable-background-networking",
+      "--disable-component-update",
+      "--disable-sync",
+      "--hide-scrollbars",
+      "--mute-audio",
+      "--remote-debugging-pipe",
+      `--user-data-dir=${profileDir}`,
+      "--window-size=1280,900",
+      "about:blank",
+    ],
+    { stdio: ["ignore", "ignore", "ignore", "pipe", "pipe"] },
+  );
+  const closed = new Promise((resolve) => {
+    child.once("error", () => resolve({ code: -1 }));
+    child.once("close", (code) => resolve({ code: Number(code ?? -1) }));
+  });
+  const hardKill = setTimeout(() => child.kill("SIGTERM"), waitMs + 30_000);
+  const consoleLines = [];
+  const exceptions = [];
+  const failedRequests = [];
+  let documentStatus = null;
+  const requestUrls = new Map();
+  const push = (list, line) => {
+    if (list.length < MAX_PREVIEW_LOG_LINES) {
+      list.push(redactPreviewCredential(line).slice(0, 500));
+    }
+  };
+  try {
+    const cdp = createCdpPipe(child);
+    const enableDomains = (sessionId) =>
+      Promise.all([
+        cdp.send("Runtime.enable", {}, sessionId),
+        cdp.send("Log.enable", {}, sessionId),
+        cdp.send("Network.enable", {}, sessionId),
+      ]).catch(() => undefined);
+    cdp.onEvent((message) => {
+      const params = message.params || {};
+      if (message.method === "Runtime.consoleAPICalled") {
+        const values = (params.args || []).map(remoteArgumentText);
+        push(consoleLines, `[console.${params.type || "log"}] ${values.join(" ")}`);
+      } else if (message.method === "Runtime.exceptionThrown") {
+        const details = params.exceptionDetails || {};
+        push(
+          exceptions,
+          details.exception?.description || details.text || "Uncaught exception",
+        );
+      } else if (message.method === "Log.entryAdded") {
+        const entry = params.entry || {};
+        if (entry.level === "error" || entry.level === "warning") {
+          push(
+            consoleLines,
+            `[${entry.level}] ${entry.text || ""}${entry.url ? ` (${entry.url})` : ""}`,
+          );
+        }
+      } else if (message.method === "Network.requestWillBeSent") {
+        if (params.requestId && requestUrls.size < 2_000) {
+          requestUrls.set(params.requestId, String(params.request?.url || ""));
+        }
+      } else if (message.method === "Network.responseReceived") {
+        const response = params.response || {};
+        const status = Number(response.status || 0);
+        if (params.type === "Document" && documentStatus === null) {
+          documentStatus = status;
+        }
+        if (status >= 400) push(failedRequests, `${status} ${response.url || ""}`);
+      } else if (message.method === "Network.loadingFailed") {
+        if (!params.canceled) {
+          push(
+            failedRequests,
+            `${params.errorText || "failed"} (${params.type || "request"}) ${requestUrls.get(params.requestId) || ""}`.trim(),
+          );
+        }
+      } else if (message.method === "Target.attachedToTarget") {
+        const sessionId = String(params.sessionId || "");
+        if (sessionId) void enableDomains(sessionId);
+      }
+    });
+    const target = await waitForPageTarget(cdp);
+    const attached = await cdp.send("Target.attachToTarget", {
+      targetId: target.targetId,
+      flatten: true,
+    });
+    const sessionId = String(attached.sessionId || "");
+    if (!sessionId) throw new Error("Chrome did not attach to the preview page.");
+    await cdp.send("Page.enable", {}, sessionId);
+    await enableDomains(sessionId);
+    await cdp.send(
+      "Target.setAutoAttach",
+      { autoAttach: true, waitForDebuggerOnStart: false, flatten: true },
+      sessionId,
+    );
+    await cdp.send("Page.navigate", { url }, sessionId);
+    await delay(waitMs);
+    const evaluated = await cdp.send(
+      "Runtime.evaluate",
+      { expression: PAGE_STATE_EXPRESSION, returnByValue: true },
+      sessionId,
+    );
+    const page = evaluated.result?.value || null;
+    const screenshot = await cdp.send(
+      "Page.captureScreenshot",
+      { format: "png", fromSurface: true, captureBeyondViewport: false },
+      sessionId,
+    );
+    let screenshotBytes = 0;
+    if (screenshot.data) {
+      const buffer = Buffer.from(screenshot.data, "base64");
+      writeFileSync(screenshotPath, buffer);
+      screenshotBytes = buffer.length;
+    }
+    await cdp.send("Browser.close").catch(() => undefined);
+    await Promise.race([closed, delay(5_000)]);
+    const blank =
+      !page || (Number(page.textLength || 0) === 0 &&
+        Number(page.visibleMediaCount || 0) === 0);
+    const problems = [
+      ...(documentStatus !== null && documentStatus >= 400
+        ? [`The preview document answered HTTP ${documentStatus}.`]
+        : []),
+      ...(exceptions.length > 0
+        ? [`${exceptions.length} uncaught exception(s) while the draft started.`]
+        : []),
+      ...(blank ? ["The page shows no text, canvas, image, svg or video after the wait."] : []),
+    ];
+    return {
+      ok: problems.length === 0,
+      skipped: false,
+      waitMs,
+      documentStatus,
+      page,
+      problems,
+      exceptions,
+      console: consoleLines,
+      failedRequests,
+      screenshot: screenshotBytes > 0
+        ? { path: screenshotPath, bytes: screenshotBytes }
+        : null,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      skipped: false,
+      error: redactPreviewCredential(String(error?.message || error)),
+      exceptions,
+      console: consoleLines,
+      failedRequests,
+      screenshot: null,
+    };
+  } finally {
+    clearTimeout(hardKill);
+    if (child.exitCode === null && child.signalCode === null) child.kill("SIGTERM");
+    await Promise.race([closed, delay(5_000)]);
+    rmSync(profileDir, { recursive: true, force: true });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/LUMINE_ADMIN.md

@@ -198,6 +198,12 @@ IP evidence, private messages, or unrelated activity. `--include-private-evidenc
 adds DOB values and verified email addresses only; exact device IDs are never
 returned.
 
+The CLI sends `identity inspect` and `identity network` as reads, so it keeps
+no copy of the result on disk; the server still records who looked, when and
+why, one audit row per call. When a case needs a kept copy (a bullying or police
+matter, say), add `--output <file>`: the result is written there with
+owner-only (0600) permissions, and nowhere else.
+
 Every inspection requires a concrete `--reason`. Before loading the evidence,
 the API commits a private `identity.inspect` audit receipt containing the real
 operator, requested target, reason, and whether private evidence was requested.
@@ -1176,7 +1182,7 @@ lumine admin identity network <userId|username> --reason <text> [--include-priva
 **Network evidence** (`users_actions` addresses, added 2026-10-04): the account's most recently used addresses (up to 8), and for each one who else acted from it.
 - An address more than 8 other accounts use is a **shared network** (an academy, a school, a café): it is only counted, never listed, because it links strangers. Teachers and students at the same academy share one.
 - An address 8 or fewer other accounts use is a **small network** (a home): every account on it is listed with its age, role and account type. The person's own linked accounts (email, device, bucket) are marked `their linked account` and never raise a flag; logged-out visits are not accounts. If the addresses cannot be read (time cap), the pack still answers, with `network_evidence_unavailable`.
-- Addresses are masked (`58.151.x.59`) with a stable `addressId` for comparing reports; `--include-private-evidence` on `identity network` shows the full address. `identity network` commits an access receipt with your reason before reading anything, like `identity inspect`.
+- Addresses are masked (`58.151.x.59`) with a stable `addressId` for comparing reports; `--include-private-evidence` on `identity network` shows the full address. `identity network` commits a server-side access audit row with your reason before reading anything, like `identity inspect`; neither leaves a local copy unless you pass `--output <file>`.
 - Only each address's newest 5,000 actions and each person's newest 5,000 are read (index-bounded, replica, time-capped), so `older history not read` can appear.
 
 **Flags.** A linked account counts as a *minor* only with a recorded age under 18, and as a *member* when it holds no teacher/staff role (most accounts record no age, so "member" does not mean student):
@@ -1362,6 +1368,28 @@ those exact files and does not depend on keeping the review copy. Re-offers
 reuse the media; a failed transaction cleans up its copied objects. Declining
 leaves the offered media as unused uploads in the creator's library.
 
+### Owner client trace (any time, read-only; added 2026-10-06)
+
+When Mikey reports a UI issue from his phone, read what his browser did
+before guessing. Only the owner's own signed-in browser records it (everyone
+else's is a no-op and the upload route refuses them); the server keeps 30 days.
+
+```bash
+lumine admin owner-trace --since 30m                       # readable timeline, oldest first
+lumine admin owner-trace --since 2026-10-06T09:00 --type route,feed-open
+lumine admin owner-trace --path /comments/123 --json        # raw rows
+```
+
+Event types: `session` (version, viewport, platform, PWA or tab), `route`
+(PUSH/POP/REPLACE, previous path, Home feed navigation/intent ids and action),
+`feed-open` (content type and id, open/comment/reward/recommend, how it was
+triggered and the tapped element's tag, card position), `scroll-anchor` (the
+scroll-anchor diagnostics: save/restore/cancel with scroll numbers),
+`content-scroll` (scrollTop at mount, when the content is ready, and 1 s/3 s
+later), `error`/`rejection` (short message and source file), `visibility`,
+`pagehide`, `trace-dropped`. Times are the phone's clock in this machine's
+time zone. Ids and paths only, never message text or other members' content.
+
 ### Reward question-bank seeding (every full daily review; added 2026-09-28)
 
 `generated-quiz` rules fill a question bank on the server: a question is