flowviant 0.125.28 → 0.125.30

package/bin/lib/reviewEnvironmentConfig.mjs

@@ -0,0 +1,104 @@
+/** Reviewed recipes plus machine-local bindings; never a cloud secret vault. */
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { git } from './git.mjs';
+
+export const ENVIRONMENT_RECIPE = '.flowviant/environment.json';
+export const ENVIRONMENT_LOCAL = '.flowviant/environment.local.json';
+export const environmentHash = value => createHash('sha256').update(value).digest('hex');
+const KEY = /^[A-Za-z_][A-Za-z0-9_]{0,99}$/;
+export const environmentKey = key => KEY.test(key) && !key.startsWith('FLOWVIANT_') && !['HOME', 'PATH', 'CODEX_HOME', 'NODE_OPTIONS', 'LD_PRELOAD'].includes(key);
+const command = value => Array.isArray(value) && value.length > 0 && value.length <= 32 && value.every(v => typeof v === 'string' && v.length > 0 && v.length <= 2000 && !/[\0\r\n]/.test(v));
+const strings = (value, max = 40) => Array.isArray(value) && value.length <= max && value.every(v => typeof v === 'string');
+
+export function repositoryPath(root, path) {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || path.includes('\\') || path.split('/').some(p => !p || p === '.' || p === '..') || /[\0\r\n]/.test(path)) throw new Error('Environment paths must be relative repository paths.');
+  const dest = resolve(root, path);
+  // Refuse links in any existing parent, including a linked .flowviant.
+  let current = resolve(root);
+  for (const part of path.split('/')) {
+    current = resolve(current, part);
+    try { if (lstatSync(current).isSymbolicLink()) throw new Error('Environment paths cannot contain symbolic links.'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  return dest;
+}
+
+export function readEnvironmentRecipe(root, ref = 'HEAD') {
+  const options = { stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 };
+  let commit;
+  try { commit = git(['rev-parse', '--verify', ref], root, options); }
+  catch (error) {
+    // Existing checks can lack a resolvable optional base ref. Without a
+    // declared recipe there is no environment feature to fail their check.
+    if (!git(['ls-tree', 'HEAD', '--', ENVIRONMENT_RECIPE], root, options)) return null;
+    throw error;
+  }
+  // Absence and a failed read are different. A malformed/unreadable declared
+  // recipe must never fall through to copying the checkout's shared env.
+  const entry = git(['ls-tree', commit, '--', ENVIRONMENT_RECIPE], root, options);
+  if (!entry) return null;
+  if (!entry.startsWith('100644 blob ') && !entry.startsWith('100755 blob ')) throw new Error('The environment recipe must be a regular tracked file.');
+  let recipe;
+  try { recipe = JSON.parse(git(['show', `${commit}:${ENVIRONMENT_RECIPE}`], root, options)); }
+  catch { throw new Error('The reviewed environment recipe is not valid JSON.'); }
+  const db = recipe?.database;
+  if (recipe.version !== 1 || !db || !['postgres', 'command'].includes(db.provider) || !strings(db.bindings) || db.bindings.length === 0 || db.bindings.some(k => !environmentKey(k)) || new Set(db.bindings).size !== db.bindings.length) throw new Error('The environment recipe needs version 1, a database provider and unique environment variable bindings.');
+  if (!command(recipe.migrate) || !command(recipe.seed)) throw new Error('The environment recipe needs migrate and seed argv arrays. Both commands must be retry-safe.');
+  if (db.provider === 'postgres' && (!environmentKey(db.adminUrlEnv ?? '') || db.bindings.includes(db.adminUrlEnv))) throw new Error('PostgreSQL needs a separate adminUrlEnv credential name.');
+  if (db.provider === 'command' && (!command(db.command) || !strings(db.credentials ?? []) || (db.credentials ?? []).some(k => !environmentKey(k) || db.bindings.includes(k)) || typeof db.source !== 'string' || !db.source.trim())) throw new Error('A database adapter needs command argv, credential names and an explicit test-data source.');
+  const files = recipe.envFiles ?? ['.env.local'];
+  if (!strings(files, 12) || new Set(files).size !== files.length) throw new Error('Environment envFiles must be unique repository paths.');
+  for (const file of files) {
+    repositoryPath(root, file);
+    if (!/(^|\/)(?:\.env(?:\.[A-Za-z0-9_-]+)*|\.dev\.vars(?:\.[A-Za-z0-9_-]+)*)$/.test(file)) throw new Error('Generated environment files must use an .env or .dev.vars filename.');
+  }
+  if (recipe.env != null && (!recipe.env || typeof recipe.env !== 'object' || Array.isArray(recipe.env) || Object.entries(recipe.env).some(([k, v]) => !environmentKey(k) || typeof v !== 'string' || v.length > 16_384 || v.includes('\0')))) throw new Error('Recipe env must contain environment variable names and string values.');
+  const ttlHours = recipe.ttlHours ?? 24;
+  if (!Number.isFinite(ttlHours) || ttlHours < 1 || ttlHours > 168) throw new Error('Environment ttlHours must be between 1 and 168.');
+  const connectors = recipe.connectors ?? [];
+  if (!strings(connectors) || connectors.some(n => !/^[A-Za-z0-9_-]{1,80}$/.test(n))) throw new Error('Environment connectors must name reviewed project MCP servers.');
+  return { recipe: { ...recipe, envFiles: files, ttlHours, connectors }, commit, root: realpathSync(root), hash: environmentHash(JSON.stringify(recipe)) };
+}
+
+export function readEnvironmentLocal(root, callerEnv = process.env) {
+  const path = repositoryPath(root, ENVIRONMENT_LOCAL);
+  if (!existsSync(path)) return { ...callerEnv };
+  try { git(['check-ignore', '--quiet', '--', ENVIRONMENT_LOCAL], root); }
+  catch { throw new Error(`${ENVIRONMENT_LOCAL} must be gitignored. Credentials stay on this machine.`); }
+  if (!lstatSync(path).isFile() || lstatSync(path).size > 128 * 1024 || (lstatSync(path).mode & 0o077)) throw new Error(`${ENVIRONMENT_LOCAL} must be a regular owner-only file (chmod 600).`);
+  let local;
+  try { local = JSON.parse(readFileSync(path, 'utf8')); } catch { throw new Error(`${ENVIRONMENT_LOCAL} is not valid JSON.`); }
+  if (!local?.env || typeof local.env !== 'object' || Array.isArray(local.env) || Object.entries(local.env).some(([key, value]) => !environmentKey(key) || typeof value !== 'string' || value.length > 16_384 || value.includes('\0'))) throw new Error(`${ENVIRONMENT_LOCAL} needs an env object with string values.`);
+  return { ...callerEnv, ...local.env };
+}
+
+export function reviewedProviderCommand(snapshot) {
+  const argv = snapshot.recipe.database.command;
+  // Like reviewed MCP launchers, referenced repo files must still be the
+  // reviewed blobs. Run providers from the checkout, never an edited worktree.
+  for (const arg of argv) {
+    if (!arg.startsWith('./') && !arg.startsWith('.flowviant/')) continue;
+    const path = arg.replace(/^\.\//, '');
+    const absolute = repositoryPath(snapshot.root, path);
+    const expected = git(['rev-parse', `${snapshot.commit}:${path}`], snapshot.root, { stdio: ['ignore', 'pipe', 'ignore'] });
+    let actual;
+    try { actual = git(['hash-object', '--no-filters', '--', absolute], snapshot.root, { stdio: ['ignore', 'pipe', 'ignore'] }); }
+    catch { throw new Error('A reviewed database adapter is missing from the checkout.'); }
+    if (actual !== expected) throw new Error('The database adapter differs from its reviewed base copy.');
+  }
+  return argv;
+}
+
+export function validateEnvironmentConnectors(snapshot) {
+  if (!snapshot.recipe.connectors.length) return;
+  let servers;
+  try { servers = JSON.parse(git(['show', `${snapshot.commit}:.mcp.json`], snapshot.root, { stdio: ['ignore', 'pipe', 'ignore'] })).mcpServers; }
+  catch { throw new Error('Environment connectors need a reviewed .mcp.json.'); }
+  for (const name of snapshot.recipe.connectors) {
+    const config = servers?.[name];
+    const values = config && [config.command, config.url, ...(config.args ?? []), ...Object.values(config.env ?? {}), ...Object.values(config.headers ?? {})];
+    if (!values?.some(value => snapshot.recipe.database.bindings.some(key => String(value).includes('${' + key + '}')))) throw new Error(`The ${name} connector must reference an isolated database binding in .mcp.json.`);
+  }
+}

package/bin/lib/reviewEnvironmentMain.mjs

@@ -0,0 +1,38 @@
+/** Private daemon verbs, also usable by runners without MCP. */
+import { spawn } from 'node:child_process';
+import { killGroup, STOP_GRACE_MS } from './processGroup.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+import { prepareWorktreeEnvironment, readWorktreeEnvironment, releaseWorktreeEnvironment } from './reviewEnvironment.mjs';
+
+export async function reviewEnvironmentMain(argv = process.argv.slice(3)) {
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  process.on('SIGINT', abort); process.on('SIGTERM', abort);
+  try {
+    const [wt, verb, separator, ...command] = argv;
+    const current = readWorktreeEnvironment(wt, process.env, { allowPending: verb === 'refresh' || verb === 'release' });
+    if (!current) throw new Error('No Flowviant environment has been prepared in this worktree.');
+    if (verb === 'refresh' && (argv.length === 2 || (argv.length === 3 && separator === '--seed'))) {
+      const next = await prepareWorktreeEnvironment(current.snapshot.root, wt, { snapshot: current.snapshot, reseed: separator === '--seed', signal: controller.signal });
+      process.stdout.write(JSON.stringify({ environment: next.record.id, state: next.record.phase, fixturesSeeded: next.record.seeded }) + '\n');
+    } else if (verb === 'release' && argv.length === 2) {
+      await releaseWorktreeEnvironment(current.snapshot.root, current.record.id, { signal: controller.signal });
+      process.stdout.write('Disposable environment released.\n');
+    } else if (verb === 'run' && separator === '--' && command.length) {
+      const child = spawn(command[0], command.slice(1), { cwd: wt, env: unattendedEnv(current.env), stdio: 'inherit', detached: true });
+      let stopTimer;
+      const stop = () => {
+        killGroup(child, 'SIGTERM');
+        stopTimer ??= setTimeout(() => killGroup(child), STOP_GRACE_MS);
+        stopTimer.unref?.();
+      };
+      controller.signal.addEventListener('abort', stop, { once: true });
+      if (controller.signal.aborted) stop();
+      await new Promise((resolve, reject) => {
+        child.once('error', () => reject(new Error('The environment command could not start.')));
+        child.once('close', code => { process.exitCode = code ?? 1; resolve(); });
+      }).finally(() => { clearTimeout(stopTimer); controller.signal.removeEventListener('abort', stop); killGroup(child); });
+    } else throw new Error('Use this worktree environment with refresh, release, or run -- <command argv>.');
+  } catch (error) { process.stderr.write(error.message + '\n'); process.exitCode = 1; }
+  finally { process.off('SIGINT', abort); process.off('SIGTERM', abort); }
+}

package/bin/lib/reviewImage.mjs

@@ -0,0 +1,58 @@
+/** One network-disabled headless canvas normalizes native engine images. */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { startReviewProcess } from './reviewProcess.mjs';
+import { chromeFlags, resolveBrowser, sandboxOff } from './shot.mjs';
+import { createCdpClient } from './pinnedCapture.mjs';
+import { childEnv } from './childEnv.mjs';
+
+export async function createReviewImage({ signal, onChild, timeoutMs = 620_000, detached = true, browser = resolveBrowser() } = {}) {
+  if (!browser || browser.viaWindows) throw new Error('Studio viewport review needs native headless Chromium on the daemon host to normalize captured images.');
+  const home = mkdtempSync(join(tmpdir(), 'flowviant-engine-image-'));
+  let process, cdp, closed = false, sessionId;
+  const close = async () => {
+    if (closed) return;
+    closed = true; cdp?.close('Engine image encoder closed.');
+    await process?.close();
+    try { rmSync(home, { recursive: true, force: true }); } catch { /* local cleanup */ }
+  };
+  const send = async (method, params = {}, session) => {
+    let timer;
+    try { return await Promise.race([cdp.send(method, params, session), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Engine image encoding timed out.')), 5000); })]); }
+    catch (error) { await close(); throw error; }
+    finally { clearTimeout(timer); }
+  };
+  try {
+    process = startReviewProcess([browser.bin, ...chromeFlags({ headlessFlag: '--headless=new', noSandbox: sandboxOff(), userDataDir: home, width: 1440, height: 900 }),
+      '--remote-debugging-pipe', '--disable-background-networking', '--disable-sync', '--disable-default-apps', '--proxy-server=http://127.0.0.1:9', '--proxy-bypass-list=<-loopback>', 'about:blank'],
+    { env: { ...childEnv(), HOME: home, USERPROFILE: home, XDG_CONFIG_HOME: home, XDG_DATA_HOME: home, XDG_CACHE_HOME: home }, signal, onChild, timeoutMs, detached, captureStdout: false, stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] });
+    cdp = createCdpClient(process.child.stdio[3], process.child.stdio[4], { maxMessageBytes: 10 * 1024 * 1024 });
+    process.done.then(() => { cdp.close('Engine image encoder exited.'); void close(); });
+    await send('Browser.getVersion');
+    await send('Browser.setDownloadBehavior', { behavior: 'deny' });
+    const { targetInfos } = await send('Target.getTargets');
+    const target = targetInfos.find(t => t.type === 'page');
+    if (!target) throw new Error('No isolated engine image canvas is available.');
+    ({ sessionId } = await send('Target.attachToTarget', { targetId: target.targetId, flatten: true }));
+    await send('Network.enable', {}, sessionId);
+    await send('Network.setBlockedURLs', { urls: ['http://*', 'https://*', 'file://*', 'ws://*', 'wss://*', 'ftp://*'] }, sessionId);
+    return { close, async encode(image) {
+      if (closed) throw new Error('Engine image encoder closed.');
+      if (!image || !['image/png', 'image/jpeg'].includes(image.mimeType) || typeof image.data !== 'string' || image.data.length > 8 * 1024 * 1024 || !/^[A-Za-z0-9+/]+={0,2}$/.test(image.data)) throw new Error('Studio MCP must return one bounded PNG/JPEG image content block.');
+      const encoded = await send('Runtime.evaluate', { awaitPromise: true, returnByValue: true, expression: `new Promise((resolve,reject)=>{
+        const image=new Image();image.onerror=()=>reject(new Error('Invalid engine image'));
+        image.onload=()=>{const width=image.naturalWidth,height=image.naturalHeight;
+          if(!width||!height||width>4096||height>4096){reject(new Error('Engine image exceeds pixel bound'));return;}
+          const scale=Math.min(1440/width,900/height),w=width*scale,h=height*scale,left=(1440-w)/2,top=(900-h)/2;
+          const canvas=document.createElement('canvas');canvas.width=1440;canvas.height=900;
+          const context=canvas.getContext('2d');context.fillStyle='#000';context.fillRect(0,0,1440,900);context.drawImage(image,left,top,w,h);
+          resolve({data:canvas.toDataURL('image/jpeg',0.65).split(',')[1],width,height,left,top,w,h});
+        };image.src=${JSON.stringify(`data:${image.mimeType};base64,${image.data}`)};
+      })` }, sessionId);
+      const result = encoded.result?.value;
+      if (encoded.exceptionDetails || !result || result.data.length > 1_000_000) throw new Error('Studio image could not be normalized within the frame bound.');
+      return result;
+    } };
+  } catch (error) { await close(); throw error; }
+}

package/bin/lib/reviewMcpClient.mjs

@@ -0,0 +1,69 @@
+/** Bounded stdio MCP client for an engine bridge, never a model service. */
+import { StringDecoder } from 'node:string_decoder';
+import { startReviewProcess } from './reviewProcess.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+
+export async function connectReviewMcp({ command, cwd, env, onChild, signal, requestTimeoutMs = 15_000, timeoutMs = 620_000, detached = true }) {
+  const process = startReviewProcess(command, { cwd, env, onChild, signal, timeoutMs, detached, captureStdout: false, stdio: ['pipe', 'pipe', 'pipe'] });
+  const pending = new Map(), decoder = new StringDecoder('utf8');
+  let serial = 0, buffer = '', closed = false;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(new Error('Studio MCP disconnected.')); }
+    pending.clear(); process.child.stdin.end(); await process.close();
+  };
+  const fail = () => { void close(); };
+  process.done.then(fail);
+  process.child.stdout.on('data', bytes => {
+    if (closed) return;
+    buffer += decoder.write(bytes);
+    if (Buffer.byteLength(buffer) > 10 * 1024 * 1024) { fail(); return; }
+    let newline;
+    while (!closed && (newline = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+      try {
+        const message = JSON.parse(line);
+        if (message.jsonrpc !== '2.0') throw new Error('Invalid MCP protocol.');
+        if (message.id != null && message.method) {
+          // This adapter supplies no sampling, elicitation or filesystem roots.
+          process.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'This review client does not support server requests.' } }) + '\n');
+        } else {
+          const entry = pending.get(message.id); if (!entry) continue;
+          pending.delete(message.id); clearTimeout(entry.timer);
+          message.error ? entry.reject(new Error(reviewDiagnostic(message.error.message))) : entry.resolve(message.result);
+        }
+      } catch { fail(); }
+    }
+  });
+  const request = (method, params, limit = requestTimeoutMs) => new Promise((resolve, reject) => {
+    if (closed) { reject(new Error('Studio MCP is disconnected.')); return; }
+    const id = ++serial;
+    const timer = setTimeout(() => { pending.delete(id); reject(new Error(`Studio MCP ${method} timed out.`)); }, limit);
+    pending.set(id, { resolve, reject, timer });
+    process.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n', error => { if (error) fail(); });
+  });
+  try {
+    const hello = await request('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'flowviant-runtime-review', version: '1' } });
+    if (!hello?.capabilities?.tools) throw new Error('The configured server exposes no MCP tools.');
+    process.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+    const tools = []; let cursor;
+    for (let page = 0; page < 8; page++) {
+      const result = await request('tools/list', cursor ? { cursor } : {});
+      if (!Array.isArray(result?.tools) || tools.length + result.tools.length > 500) throw new Error('Studio MCP returned an invalid tool catalog.');
+      tools.push(...result.tools); cursor = result.nextCursor;
+      if (!cursor) break;
+      if (page === 7) throw new Error('Studio MCP tool catalog exceeded its page bound.');
+    }
+    return { tools, close, async call(name, args, limit) {
+      if (!tools.some(tool => tool.name === name)) throw new Error(`Studio MCP does not expose ${name}. Update Studio and enable its built-in MCP server.`);
+      const result = await request('tools/call', { name, arguments: args }, limit);
+      if (result?.isError) throw new Error(reviewDiagnostic((result.content ?? []).filter(c => c.type === 'text').map(c => c.text).join('\n')).slice(0, 1000) || `Studio MCP ${name} failed.`);
+      return result;
+    } };
+  } catch (error) { await close(); throw error; }
+}
+
+export function mcpText(result) {
+  return (result?.content ?? []).filter(c => c.type === 'text' && typeof c.text === 'string').map(c => c.text).join('\n');
+}

package/bin/lib/reviewProcess.mjs

@@ -0,0 +1,51 @@
+/** Own every runtime child and bound its output, cancellation and lifetime. */
+import { spawn } from 'node:child_process';
+import { killGroup } from './processGroup.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+import { scrub } from './uplinkScrub.mjs';
+import { workLanesStopped } from './standDownGate.mjs';
+
+export function startReviewProcess(argv, { cwd, env = process.env, display = false, input, signal, onChild = () => () => {}, timeoutMs = 600_000, binary = false, maxBytes = 64 * 1024, stdio, captureStdout = true, detached = true } = {}) {
+  signal?.throwIfAborted();
+  if (workLanesStopped()) throw new Error('The daemon is stopping. Review has not started.');
+  const child = spawn(argv[0], argv.slice(1), { cwd, env: unattendedEnv(env, { display }), detached, stdio: stdio ?? ['pipe', 'pipe', 'pipe'] });
+  let timer, untrack = () => {}, settled = false, total = 0, stdout = [], tail = '', exit;
+  let resolveExit;
+  const done = new Promise(resolve => { resolveExit = resolve; });
+  const finish = result => {
+    if (settled) return;
+    settled = true; exit = result; clearTimeout(timer); signal?.removeEventListener('abort', abort); untrack();
+    killGroup(child);
+    resolveExit({ ...result, output: tail, data: binary ? Buffer.concat(stdout) : undefined });
+  };
+  const terminate = reason => { killGroup(child); child.stdout?.destroy(); child.stderr?.destroy(); finish({ code: null, error: reason }); };
+  const abort = () => terminate('Review was interrupted.');
+  const diagnostics = bytes => { tail = scrub(tail + bytes.toString()).slice(-maxBytes); };
+  child.stdout?.on('data', bytes => {
+    if (!captureStdout) return;
+    if (binary) {
+      total += bytes.length;
+      if (total > maxBytes) { terminate('Review capture exceeded its byte bound.'); return; }
+      stdout.push(bytes);
+    } else diagnostics(bytes);
+  });
+  child.stderr?.on('data', diagnostics);
+  child.once('error', () => finish({ code: null, error: `Could not start ${argv[0]}. Check that it is installed.` }));
+  child.once('close', code => finish({ code }));
+  child.stdin?.on('error', () => {});
+  if (input !== undefined) child.stdin?.end(input);
+  else if (stdio == null) child.stdin?.end();
+  try { untrack = onChild(child) ?? (() => {}); }
+  catch (error) { terminate('The review process could not be tracked.'); throw error; }
+  timer = setTimeout(() => terminate('Review reached its time limit.'), timeoutMs); timer.unref?.();
+  signal?.addEventListener('abort', abort, { once: true }); if (signal?.aborted) abort();
+  return { child, done, running: () => !settled, result: () => exit, output: () => tail,
+    async close() { terminate('Review stopped.'); await done; } };
+}
+
+export async function reviewExec(argv, options) {
+  const process = startReviewProcess(argv, options);
+  const result = await process.done;
+  if (result.error || result.code !== 0) throw new Error(result.error ?? `Review command exited ${result.code}. ${result.output}`);
+  return result;
+}

package/bin/lib/reviewTargets.mjs

@@ -0,0 +1,50 @@
+/** A reviewed recipe selects workflows; languages do not select viewers. */
+import { accessSync, constants, realpathSync } from 'node:fs';
+import { delimiter, isAbsolute, relative, resolve } from 'node:path';
+import { git } from './git.mjs';
+import { environmentKey } from './reviewEnvironmentConfig.mjs';
+import { robloxConfiguration } from './robloxReview.mjs';
+
+export const REVIEW_RECIPE = '.flowviant/review.json';
+const quiet = { stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 128 * 1024 };
+const nameOk = value => typeof value === 'string' && /^[A-Za-z0-9_-]{1,60}$/.test(value);
+const commandOk = value => Array.isArray(value) && value.length > 0 && value.length <= 40 && value.every(v => typeof v === 'string' && v.length > 0 && v.length <= 2000 && !/[\0\r\n]/.test(v));
+
+export function reviewCwd(wt, cwd = '.') {
+  if (typeof cwd !== 'string' || isAbsolute(cwd) || /[\0\r\n\\]/.test(cwd)) throw new Error('Review cwd must be inside this worktree.');
+  const path = realpathSync(resolve(wt, cwd)), rel = relative(realpathSync(wt), path);
+  if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) throw new Error('Review cwd must be inside this worktree.');
+  return path;
+}
+
+export function commandOnPath(command, env = process.env) {
+  const candidates = isAbsolute(command) ? [command] : command.includes('/') || command.includes('\\') ? [] : (env.PATH ?? '').split(delimiter).map(dir => resolve(dir, command));
+  return candidates.find(path => { try { accessSync(path, constants.X_OK); return true; } catch { return false; } }) ?? null;
+}
+
+export function readReviewTargets(root, ref = 'HEAD') {
+  const commit = git(['rev-parse', '--verify', ref], root, quiet);
+  const entry = git(['ls-tree', commit, '--', REVIEW_RECIPE], root, quiet);
+  if (!entry) return { root, commit, targets: {} };
+  if (!/^100(?:644|755) blob /.test(entry)) throw new Error('The review recipe must be a regular tracked file.');
+  let recipe;
+  try { recipe = JSON.parse(git(['show', `${commit}:${REVIEW_RECIPE}`], root, quiet)); }
+  catch { throw new Error('The reviewed review.json is not valid JSON.'); }
+  if (recipe?.version !== 1 || !recipe.targets || typeof recipe.targets !== 'object' || Array.isArray(recipe.targets) || Object.keys(recipe.targets).length > 24) throw new Error('Review recipes need version 1 and at most 24 named targets.');
+  const targets = Object.create(null);
+  for (const [name, target] of Object.entries(recipe.targets)) {
+    if (!nameOk(name) || !target || !['command', 'browser', 'desktop', 'bridge', 'roblox'].includes(target.adapter) || !commandOk(target.command)) throw new Error('Each review target needs a name, supported adapter and command argv.');
+    if (target.adapter === 'roblox') robloxConfiguration(target.configuration);
+    if (target.cwd != null && (typeof target.cwd !== 'string' || target.cwd.length > 500 || isAbsolute(target.cwd) || /[\0\r\n\\]/.test(target.cwd))) throw new Error(`Invalid review cwd for ${name}.`);
+    const timeoutSeconds = target.timeoutSeconds ?? (target.adapter === 'command' ? 120 : 600);
+    if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > 600) throw new Error(`Review target ${name} timeoutSeconds must be 1–600.`);
+    if (target.adapter !== 'command' && (typeof target.fixture !== 'string' || target.fixture.trim().length < 12 || target.fixture.length > 2000)) throw new Error(`Review target ${name} needs a disposable fixture description.`);
+    if (target.adapter === 'browser' && (!Number.isInteger(target.port) || target.port < 0 || target.port > 65535 || (target.port === 0 && !target.command.some(arg => arg.includes('${PORT}'))) || (target.hostname != null && target.hostname !== 'localhost') || (target.scheme != null && !['http', 'https'].includes(target.scheme)))) throw new Error(`Review target ${name} needs a valid local port/protocol (port 0 requires a PORT placeholder in command argv).`);
+    if (target.adapter === 'browser' && target.path != null && (typeof target.path !== 'string' || !target.path.startsWith('/') || target.path.startsWith('//') || /[\x00-\x20\\]/.test(target.path) || target.path.length > 2000 || new URL(target.path, 'http://preview.invalid').pathname.startsWith('//'))) throw new Error(`Review target ${name} needs a local path.`);
+    if (target.platforms != null && (!Array.isArray(target.platforms) || target.platforms.length > 3 || target.platforms.some(p => !['linux', 'darwin', 'win32'].includes(p)))) throw new Error(`Review target ${name} platforms must name operating systems.`);
+    if (target.configuration != null && (typeof target.configuration !== 'object' || Array.isArray(target.configuration) || Buffer.byteLength(JSON.stringify(target.configuration)) > 16_000)) throw new Error(`Review target ${name} bridge configuration exceeds its bound.`);
+    if (target.env != null && (!Array.isArray(target.env) || target.env.length > 40 || target.env.some(key => typeof key !== 'string' || !environmentKey(key)))) throw new Error(`Review target ${name} env must name explicitly selected runtime variables.`);
+    targets[name] = { ...target, cwd: target.cwd ?? '.', timeoutSeconds };
+  }
+  return { root: realpathSync(root), commit, targets };
+}

package/bin/lib/robloxReview.mjs

@@ -0,0 +1,234 @@
+/** Studio viewport adapter. All engine operations name one verified fixture. */
+import { readFileSync, realpathSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { basename, isAbsolute, relative, resolve } from 'node:path';
+import { connectReviewMcp, mcpText } from './reviewMcpClient.mjs';
+import { createReviewImage } from './reviewImage.mjs';
+import { reviewDiagnostic } from './uiReviewBrowser.mjs';
+
+const MARKER = 'FLOWVIANT_REVIEW_PROBE:';
+const CLIENT_PROBE = `local camera=workspace.CurrentCamera
+return '${MARKER}'..game:GetService('HttpService'):JSONEncode({player=game:GetService('Players').LocalPlayer ~= nil,width=camera and camera.ViewportSize.X or 0,height=camera and camera.ViewportSize.Y or 0,session=game:GetAttribute('FlowviantReviewSession')})`;
+const sha = value => createHash('sha256').update(value).digest('hex');
+const normalize = value => value.replace(/\r\n/g, '\n');
+// Decimal byte escapes preserve Unicode without creating hundreds of call
+// arguments (long UTF-8 names can exceed Luau's register limit).
+const luauString = value => '"' + [...Buffer.from(value)].map(byte => '\\' + String(byte).padStart(3, '0')).join('') + '"';
+const pathOk = value => Array.isArray(value) && value.length > 0 && value.length <= 20 && value.every(part => typeof part === 'string' && part.length > 0 && part.length <= 150 && !/[\x00-\x1f]/.test(part));
+
+export function robloxConfiguration(config) {
+  if (!config || typeof config.studioName !== 'string' || config.studioName.length < 1 || config.studioName.length > 250 || /[\x00-\x1f]/.test(config.studioName)) throw new Error('Roblox review needs the exact Studio fixture name (optionally containing ${WORKTREE}).');
+  if (config.startPlay != null && typeof config.startPlay !== 'boolean') throw new Error('Roblox startPlay must be a boolean.');
+  if (!Array.isArray(config.scripts) || config.scripts.length < 1 || config.scripts.length > 40 || config.scripts.some(script => !script || typeof script.file !== 'string' || !script.file || script.file.length > 500 || isAbsolute(script.file) || script.file.split('/').includes('..') || /[\x00-\x1f\\]/.test(script.file) || !/\.(?:lua|luau)$/.test(script.file) || !pathOk(script.path))) throw new Error('Roblox review needs 1–40 Lua/Luau files mapped to explicit Studio instance path segments.');
+  if (new Set(config.scripts.map(s => s.file)).size !== config.scripts.length || new Set(config.scripts.map(s => JSON.stringify(s.path))).size !== config.scripts.length) throw new Error('Roblox source mappings must be unique.');
+  return { studioName: config.studioName, startPlay: config.startPlay ?? true, scripts: config.scripts };
+}
+
+function values(result) {
+  const out = [];
+  const visit = (value, depth = 0) => {
+    if (depth > 5) return;
+    out.push(value);
+    if (typeof value === 'string') { try { visit(JSON.parse(value), depth + 1); } catch { /* ordinary text */ } }
+    else if (value && typeof value === 'object') for (const entry of Object.values(value)) visit(entry, depth + 1);
+  };
+  visit(result.structuredContent); for (const item of result.content ?? []) if (item.type === 'text') visit(item.text);
+  return out;
+}
+
+export function studioPlayState(result) {
+  const states = new Set();
+  const mode = value => {
+    if (typeof value !== 'string') return;
+    if (/^(edit|stopped|stop)$/i.test(value)) states.add('edit');
+    if (/^(play|playing|run|running)$/i.test(value)) states.add('play');
+  };
+  for (const value of values(result)) {
+    if (typeof value === 'string') {
+      const match = /(?:^|\n)\s*(?:current\s+)?(?:studio\s+)?(?:play\s*(?:state|mode)|state|mode)\s*:\s*(Edit|Stopped|Playing|Play|Running|Run)\s*(?:$|\n)/i.exec(value);
+      if (match) mode(match[1]);
+    } else if (value && !Array.isArray(value) && typeof value === 'object') {
+      for (const key of ['playState', 'play_state', 'playMode', 'play_mode', 'state']) mode(value[key]);
+      for (const key of ['isPlaying', 'is_playing', 'isRunning', 'is_running']) if (typeof value[key] === 'boolean') states.add(value[key] ? 'play' : 'edit');
+    }
+  }
+  if (states.size !== 1) throw new Error('Studio did not report an unambiguous supported play state. No play session was changed.');
+  return [...states][0];
+}
+
+function probeValue(result) {
+  for (const value of values(result)) if (typeof value === 'string') {
+    const index = value.indexOf(MARKER);
+    if (index >= 0) { try { return JSON.parse(value.slice(index + MARKER.length)); } catch { /* require a complete probe result */ } }
+  }
+  throw new Error('Studio did not return the complete source-binding probe.');
+}
+
+export function studioProbe(config) {
+  return `local paths={${config.scripts.map(s => `{${s.path.map(luauString).join(',')}}`).join(',')}}
+local sources={}
+local checked=0
+for _,path in ipairs(paths) do
+  local node=game
+  for _,name in ipairs(path) do
+    local found=nil
+    for _,child in ipairs(node:GetChildren()) do
+      checked+=1
+      if checked%500==0 then task.wait() end
+      if child.Name==name then if found then error('Ambiguous review source path') end found=child end
+    end
+    if not found then error('Missing review source path') end
+    node=found
+  end
+  if not node:IsA('LuaSourceContainer') then error('Review source is not a script') end
+  local source=node.Source
+  if #source>131072 then error('Review source exceeds byte bound') end
+  table.insert(sources,source)
+end
+return '${MARKER}'..game:GetService('HttpService'):JSONEncode({fixture=game:GetService('ReplicatedStorage'):GetAttribute('FlowviantReviewWorktree'),sources=sources})`;
+}
+
+export async function openRobloxPage({ command, cwd, worktree, configuration, env, signal, onChild, onFrame = () => {}, onChange = () => {}, timeoutMs = 600_000,
+  connect = connectReviewMcp, imageFactory = createReviewImage, frameIntervalMs = 2000, startupWaitMs = 10_000 }) {
+  const config = robloxConfiguration(configuration), wt = realpathSync(worktree), fixture = basename(wt);
+  const expectedName = config.studioName.replaceAll('${WORKTREE}', fixture);
+  let mcp, encoder, studioId, ownedPlay = false, marked = false, closed = false, closePromise, timer, epoch = 0, captureSerial = 0, privateUsed = false, lastImage, queue = Promise.resolve();
+  const session = randomUUID();
+  const sourceHashes = [];
+  const tool = (name, args = {}, limit) => mcp.call(name, { ...args, studio_id: studioId }, limit);
+  const serial = fn => { const result = queue.catch(() => {}).then(fn); queue = result; return result; };
+  const close = () => {
+    if (closePromise) return closePromise;
+    closed = true; epoch++; clearTimeout(timer);
+    closePromise = (async () => {
+      // Only stop a play session this adapter started; never close Studio.
+      try {
+        await queue.catch(() => {});
+        if (ownedPlay && marked) {
+          const current = probeValue(await tool('execute_luau', { datamodel_type: 'Client', code: CLIENT_PROBE }, 4000));
+          if (current.session !== session) ownedPlay = false;
+        }
+        if (ownedPlay) await tool('start_stop_play', { is_start: false }, 8000);
+      }
+      finally { await Promise.allSettled([mcp?.close(), encoder?.close()]); }
+    })();
+    return closePromise;
+  };
+  const capture = async () => {
+    const viewport = probeValue(await tool('execute_luau', { datamodel_type: 'Client', code: CLIENT_PROBE }));
+    if (ownedPlay && marked && viewport.session !== session) { ownedPlay = false; throw new Error('Studio play was replaced outside this review; the replacement session was left alone.'); }
+    if (viewport.player !== true || !(viewport.width > 0 && viewport.height > 0)) throw new Error('No player camera viewport is available in Studio.');
+    const result = await tool('screen_capture', { capture_id: `Flowviant_${epoch}_${++captureSerial}` });
+    const images = (result.content ?? []).filter(c => c.type === 'image');
+    if (images.length !== 1) throw new Error('Studio screen_capture must return one native image content block.');
+    const image = await encoder.encode(images[0]);
+    if (Math.abs((image.width / image.height) / (viewport.width / viewport.height) - 1) > 0.01) throw new Error('Studio capture and player viewport aspect ratios differ; coordinate input cannot be mapped reliably.');
+    return { ...image, inputWidth: viewport.width, inputHeight: viewport.height };
+  };
+  const stream = async () => {
+    const current = epoch;
+    try { const image = await serial(capture); if (!closed && current === epoch) { lastImage = image; onFrame({ type: 'frame', data: image.data, width: 1440, height: 900 }); } }
+    catch (error) { if (!closed && current === epoch) { onChange({ error: reviewDiagnostic(error.message) }); void close().catch(() => {}); } }
+    finally { if (!closed && current === epoch) timer = setTimeout(stream, frameIntervalMs); }
+  };
+  try {
+    signal?.throwIfAborted();
+    // Keep dependencies alive through the outer bridge's 30-second cleanup
+    // grace, including a queued capture plus session-check/stop round trips.
+    mcp = await connect({ command, cwd, env, onChild, timeoutMs: timeoutMs + 35_000, detached: false });
+    for (const required of ['list_roblox_studios', 'get_studio_state', 'execute_luau', 'screen_capture', 'user_mouse_input', 'user_keyboard_input', ...(config.startPlay ? ['start_stop_play'] : [])]) {
+      if (!mcp.tools.some(t => t.name === required)) throw new Error(`Studio MCP is missing ${required}. Update Studio and enable its built-in MCP server.`);
+    }
+    const listed = await mcp.call('list_roblox_studios', {});
+    const studios = values(listed).find(value => value && !Array.isArray(value) && Array.isArray(value.studios))?.studios;
+    if (!studios) throw new Error('Studio MCP did not return a supported Studio instance list.');
+    const selected = studios.filter(studio => studio.name === expectedName && typeof studio.id === 'string');
+    if (selected.length !== 1) throw new Error(`Open exactly one disposable Studio fixture named ${expectedName}. ${selected.length ? 'Several matching instances are connected.' : 'No matching instance is connected.'}`);
+    studioId = selected[0].id;
+    const initial = studioPlayState(await tool('get_studio_state'));
+    if (config.startPlay && initial !== 'edit') throw new Error('This Studio fixture already has a play session. Return it to Edit mode, or configure startPlay:false to watch the existing session.');
+    const loaded = probeValue(await tool('execute_luau', { datamodel_type: 'Edit', code: studioProbe(config) }));
+    if (loaded.fixture !== fixture) throw new Error('Studio fixture is not bound to this worktree. Set the FlowviantReviewWorktree attribute on ReplicatedStorage to the worktree folder name in the disposable fixture.');
+    if (!Array.isArray(loaded.sources) || loaded.sources.length !== config.scripts.length) throw new Error('Studio did not return every mapped source.');
+    for (let index = 0; index < config.scripts.length; index++) {
+      const source = config.scripts[index], file = realpathSync(resolve(wt, source.file)), rel = relative(wt, file);
+      if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) throw new Error('A mapped Studio source escapes the worktree.');
+      const bytes = readFileSync(file); if (bytes.length > 128 * 1024 || typeof loaded.sources[index] !== 'string' || loaded.sources[index].length > 128 * 1024) throw new Error('Mapped Studio sources exceed the per-script bound.');
+      if (normalize(bytes.toString('utf8')) !== normalize(loaded.sources[index])) throw new Error(`Studio has stale/different code for ${source.file}. Sync this worktree into its fixture before review.`);
+      sourceHashes.push({ file: source.file, sha256: sha(normalize(bytes.toString('utf8'))) });
+    }
+    encoder = await imageFactory({ onChild, timeoutMs: timeoutMs + 35_000, detached: false });
+    signal?.throwIfAborted();
+    if (config.startPlay) {
+      if (studioPlayState(await tool('get_studio_state')) !== 'edit') throw new Error('Studio started playing during review setup; that existing session was left alone.');
+      signal?.throwIfAborted(); ownedPlay = true; await tool('start_stop_play', { is_start: true });
+    }
+    signal?.throwIfAborted();
+    if (studioPlayState(await tool('get_studio_state')) !== 'play') throw new Error('Studio did not enter play mode; no gameplay input was enabled.');
+    // Verify Client context rather than treating server-only Run as a player.
+    let player = false;
+    const until = Date.now() + startupWaitMs;
+    do {
+      signal?.throwIfAborted();
+      try {
+        const client = probeValue(await tool('execute_luau', { datamodel_type: 'Client', code: CLIENT_PROBE }, Math.max(1, Math.min(2000, until - Date.now()))));
+        player = client.player === true && client.width > 0 && client.height > 0;
+      } catch { /* Client context can arrive after the play-state transition. */ }
+      if (player || Date.now() >= until) break;
+      await new Promise(resolve => setTimeout(resolve, Math.min(250, until - Date.now())));
+    } while (Date.now() < until);
+    if (!player) throw new Error('No local player was measured in the Studio Client context.');
+    if (ownedPlay) {
+      const receipt = probeValue(await tool('execute_luau', { datamodel_type: 'Client', code: `game:SetAttribute('FlowviantReviewSession', '${session}')
+return '${MARKER}'..game:GetService('HttpService'):JSONEncode({session=game:GetAttribute('FlowviantReviewSession')})` }));
+      if (receipt.session !== session) throw new Error('Studio did not acknowledge the owned play-session marker.');
+      marked = true;
+    }
+    timer = setTimeout(stream, frameIntervalMs);
+    return { close,
+      async setPrivate(privateInput) { epoch++; clearTimeout(timer); lastImage = null; if (privateInput) privateUsed = true; await queue.catch(() => {}); if (!closed) timer = setTimeout(stream, frameIntervalMs); },
+      async snapshot() {
+        const current = epoch;
+        return serial(async () => {
+          if (closed) throw new Error('Studio review ended.');
+          if (studioPlayState(await tool('get_studio_state')) !== 'play') throw new Error('The Studio play session ended.');
+          const image = await capture();
+          let logs = '';
+          if (!privateUsed && mcp.tools.some(t => t.name === 'get_console_output')) {
+            try { logs = reviewDiagnostic(mcpText(await tool('get_console_output'))).slice(-4000); }
+            catch (error) { logs = `Console unavailable: ${reviewDiagnostic(error.message)}`; }
+          }
+          if (closed || current !== epoch) throw new Error('Studio control changed during capture.');
+          lastImage = image;
+          return { data: image.data, observation: JSON.stringify({ studio: expectedName, sourceHashes, console: privateUsed ? 'Console omitted after private control.' : logs,
+            note: 'Studio viewport observation. Mapped script sources matched at startup; assets and unmapped scripts are unverified. Captures/input do not establish a passing gameplay test. Studio sign-in dialogs require the Windows host.' }), diagnostics: [] };
+        });
+      },
+      async act(input) {
+        return serial(async () => {
+          if (closed) throw new Error('Studio review ended.');
+          if (input.selector || input.type === 'navigate') throw new Error('Studio supports viewport input; browser navigation and DOM selectors do not apply.');
+          if (studioPlayState(await tool('get_studio_state')) !== 'play') throw new Error('The Studio play session ended.');
+          if (ownedPlay && marked) {
+            const current = probeValue(await tool('execute_luau', { datamodel_type: 'Client', code: CLIENT_PROBE }));
+            if (current.session !== session) { ownedPlay = false; throw new Error('Studio play was replaced outside this review; the replacement session was left alone.'); }
+          }
+          const base = { datamodel_type: 'Client' };
+          if (input.type === 'click') {
+            const image = lastImage;
+            if (!image || input.x < image.left || input.y < image.top || input.x >= image.left + image.w || input.y >= image.top + image.h) throw new Error('Click inside the captured Studio viewport.');
+            await tool('user_mouse_input', { ...base, actions: [{ action: 'mouseButtonClick', mouse_button: 'left', x: Math.floor((input.x - image.left) * image.inputWidth / image.w), y: Math.floor((input.y - image.top) * image.inputHeight / image.h) }] });
+          } else if (input.type === 'type') await tool('user_keyboard_input', { ...base, actions: [{ action: 'textInput', text_inputs: input.text }] });
+          else if (input.type === 'key') {
+            const key = ({ Enter: 'Return', ArrowUp: 'Up', ArrowDown: 'Down', ArrowLeft: 'Left', ArrowRight: 'Right' })[input.key] ?? input.key;
+            await tool('user_keyboard_input', { ...base, actions: [{ action: 'keyPress', key_code: key }] });
+          } else if (input.type === 'scroll' && input.deltaY !== 0) {
+            if (!lastImage) throw new Error('Observe the Studio viewport before scrolling.');
+            await tool('user_mouse_input', { ...base, actions: Array.from({ length: Math.min(10, Math.ceil(Math.abs(input.deltaY) / 100)) }, () => ({ action: input.deltaY < 0 ? 'scrollUp' : 'scrollDown', x: Math.floor(lastImage.inputWidth / 2), y: Math.floor(lastImage.inputHeight / 2) })) });
+          }
+          else if (!['snapshot', 'scroll'].includes(input.type)) throw new Error('Studio supports viewport input; browser navigation and DOM selectors do not apply.');
+        });
+      },
+    };
+  } catch (error) { await close().catch(() => {}); throw error; }
+}