@notis_ai/cli 0.2.18 → 0.2.19

package/dist/view-renderer/src/png.js

@@ -0,0 +1,213 @@
+import { Readable } from 'node:stream';
+import { createDeflate, createInflate, crc32, inflateSync } from 'node:zlib';
+import { ViewRenderError } from './errors.js';
+
+/**
+ * Stitch full-page screenshot slices into one PNG without ever holding the
+ * whole page as raw pixels. Chromium rasterizes a full-page capture in one go,
+ * so its memory grows with the page area; slices keep that peak flat.
+ */
+const SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const CHANNELS = { 0: 1, 2: 3, 4: 2, 6: 4 };
+// Chunks that describe the image as a whole, never its pixels or its size.
+const KEEP = new Set(['sRGB', 'gAMA', 'cHRM', 'iCCP', 'pHYs']);
+
+function invalid() { return new ViewRenderError('render_failed', 'The view could not be rendered under its current access.', 500); }
+
+export function parsePng(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 33 || !buffer.subarray(0, 8).equals(SIGNATURE)) throw invalid();
+  let offset = 8, header, ended = false;
+  const idat = [], ancillary = [];
+  while (offset + 12 <= buffer.length) {
+    const length = buffer.readUInt32BE(offset);
+    const type = buffer.toString('latin1', offset + 4, offset + 8);
+    const end = offset + 12 + length;
+    if (end > buffer.length) throw invalid();
+    const data = buffer.subarray(offset + 8, offset + 8 + length);
+    if (type === 'IHDR') {
+      header = { width: data.readUInt32BE(0), height: data.readUInt32BE(4), bitDepth: data[8], colorType: data[9], interlace: data[12] };
+    } else if (type === 'IDAT') idat.push(data);
+    else if (type === 'IEND') { ended = true; break; }
+    else if (!idat.length && KEEP.has(type)) ancillary.push(buffer.subarray(offset, end));
+    offset = end;
+  }
+  if (!header || !ended || !idat.length || header.bitDepth !== 8 || !(header.colorType in CHANNELS) || header.interlace !== 0) throw invalid();
+  return { ...header, channels: CHANNELS[header.colorType], idat: idat.length === 1 ? idat[0] : Buffer.concat(idat), ancillary };
+}
+
+function paeth(a, b, c) {
+  const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+
+/** Undo one scanline's filter in place, given the previous unfiltered row (or zeros). */
+function unfilterRow(filter, row, prior, bpp) {
+  for (let i = 0; i < row.length; i++) {
+    const a = i >= bpp ? row[i - bpp] : 0, b = prior ? prior[i] : 0, c = prior && i >= bpp ? prior[i - bpp] : 0;
+    switch (filter) {
+      case 0: break;
+      case 1: row[i] = (row[i] + a) & 0xff; break;
+      case 2: row[i] = (row[i] + b) & 0xff; break;
+      case 3: row[i] = (row[i] + ((a + b) >> 1)) & 0xff; break;
+      case 4: row[i] = (row[i] + paeth(a, b, c)) & 0xff; break;
+      default: throw invalid();
+    }
+  }
+}
+
+function rawRows(png) {
+  const stride = png.width * png.channels;
+  const raw = inflateSync(png.idat);
+  if (raw.length !== png.height * (stride + 1)) throw invalid();
+  return { raw, stride };
+}
+
+/** Decode to 8-bit RGBA; used for slices whose format differs and in tests. */
+export function decodePng(buffer) {
+  const png = parsePng(buffer);
+  const { raw, stride } = rawRows(png);
+  const pixels = Buffer.alloc(png.width * png.height * 4);
+  let prior;
+  for (let y = 0; y < png.height; y++) {
+    const start = y * (stride + 1);
+    const row = raw.subarray(start + 1, start + 1 + stride);
+    unfilterRow(raw[start], row, prior, png.channels);
+    prior = row;
+    toRgba(row, png.colorType, png.width, pixels, y * png.width * 4);
+  }
+  return { width: png.width, height: png.height, pixels };
+}
+
+/** One unfiltered row of the given colour type, written as RGBA at offset. */
+function toRgba(row, colorType, width, out, offset) {
+  const channels = CHANNELS[colorType];
+  for (let x = 0; x < width; x++) {
+    const source = x * channels, target = offset + x * 4;
+    if (colorType === 6) row.copy(out, target, source, source + 4);
+    else if (colorType === 2) { row.copy(out, target, source, source + 3); out[target + 3] = 255; }
+    else if (colorType === 4) { out.fill(row[source], target, target + 3); out[target + 3] = row[source + 1]; }
+    else { out.fill(row[source], target, target + 3); out[target + 3] = 255; }
+  }
+}
+
+function chunk(type, data) {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(data.length, 0); head.write(type, 4, 'latin1');
+  const tail = Buffer.alloc(4);
+  tail.writeUInt32BE(crc32(data, crc32(head.subarray(4))) >>> 0, 0);
+  return Buffer.concat([head, data, tail]);
+}
+
+/**
+ * Rows of one slice in the output's format, each with its filter byte. Only the
+ * first row changes: its filter read a zero row above it, so it is unfiltered.
+ */
+function sliceRows(png, target) {
+  if (png.colorType === target.colorType) {
+    const { raw, stride } = rawRows(png);
+    const first = raw.subarray(1, 1 + stride);
+    unfilterRow(raw[0], first, undefined, png.channels);
+    raw[0] = 0;
+    return raw;
+  }
+  const decoded = decodePng(Buffer.concat([SIGNATURE, chunk('IHDR', ihdr(png)), chunk('IDAT', png.idat), chunk('IEND', Buffer.alloc(0))]));
+  const out = Buffer.alloc(png.height * (png.width * 4 + 1));
+  for (let y = 0; y < png.height; y++) decoded.pixels.copy(out, y * (png.width * 4 + 1) + 1, y * png.width * 4, (y + 1) * png.width * 4);
+  return out;
+}
+
+function ihdr({ width, height, colorType }) {
+  const data = Buffer.alloc(13);
+  data.writeUInt32BE(width, 0); data.writeUInt32BE(height, 4);
+  data[8] = 8; data[9] = colorType; // compression, filter and interlace stay 0
+  return data;
+}
+
+/**
+ * Stitch PNG slices, top to bottom, of one equal width, as they arrive: each
+ * slice is compressed into the output when it is added and is not kept, so the
+ * whole page is never held as pixels. Slices that share the first one's colour
+ * type keep it; any mix is written as RGBA. Stitching adds no size limit of its
+ * own: the output is refused once its compressed bytes pass maxBytes, by the add
+ * that produces them or, for bytes the compressor still holds, by finish.
+ */
+export function createPngStitcher({ maxBytes = Infinity, level = 6 } = {}) {
+  const tooLarge = () => new ViewRenderError('render_too_large', 'The PNG exceeds the render transport limit; nothing was cropped.', 413);
+  // overhead: every byte of the PNG besides the compressed pixels, so the limit is on the whole file.
+  let first, colorType, height = 0, out, overhead = 0;
+  const over = () => out.size + overhead > maxBytes;
+  function encoder() {
+    const state = { compressed: [], size: 0, crc: crc32('IDAT'), deflate: createDeflate({ level }) };
+    state.deflate.on('data', data => { state.size += data.length; state.crc = crc32(data, state.crc); state.compressed.push(data); });
+    state.finished = new Promise((resolve, reject) => { state.deflate.once('end', resolve); state.deflate.once('error', reject); });
+    state.finished.catch(() => {});
+    return state;
+  }
+  async function write(rows) {
+    await new Promise((resolve, reject) => out.deflate.write(rows, error => (error ? reject(error) : resolve())));
+    if (over()) { out.deflate.destroy(); throw tooLarge(); }
+  }
+  /** Re-encode what is written so far as RGBA, one row at a time, never the whole page. */
+  async function upgradeToRgba() {
+    const old = out;
+    old.deflate.end();
+    await old.finished;
+    out = encoder();
+    const stride = first.width * CHANNELS[colorType];
+    let carry = Buffer.alloc(0), prior;
+    for await (const data of Readable.from(old.compressed).pipe(createInflate())) {
+      carry = carry.length ? Buffer.concat([carry, data]) : data;
+      const rows = Math.floor(carry.length / (stride + 1));
+      if (!rows) continue;
+      const batch = Buffer.alloc(rows * (first.width * 4 + 1));
+      for (let y = 0; y < rows; y++) {
+        const row = Buffer.from(carry.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1)));
+        unfilterRow(carry[y * (stride + 1)], row, prior, CHANNELS[colorType]);
+        toRgba(row, colorType, first.width, batch, y * (first.width * 4 + 1) + 1);
+        prior = row;
+      }
+      carry = carry.subarray(rows * (stride + 1));
+      await write(batch);
+    }
+    if (carry.length) throw invalid();
+    old.compressed.length = 0;
+    colorType = 6;
+  }
+  return {
+    async add(slice) {
+      const png = parsePng(slice);
+      if (png.height < 1 || (first && png.width !== first.width)) throw invalid();
+      if (!first) {
+        // Keep only the width and copies of the kept chunks, never the first slice itself.
+        first = { width: png.width, ancillary: png.ancillary.map(part => Buffer.from(part)) };
+        colorType = png.colorType; out = encoder();
+        // Signature, IHDR, the kept chunks, the IDAT head and CRC, and IEND.
+        overhead = 8 + 25 + first.ancillary.reduce((total, part) => total + part.length, 0) + 12 + 12;
+      }
+      else if (png.colorType !== colorType && colorType !== 6) await upgradeToRgba();
+      // Raw rows of one slice at a time: never the whole page.
+      await write(sliceRows(png, { colorType }));
+      height += png.height;
+    },
+    async finish() {
+      if (!first) throw invalid();
+      out.deflate.end();
+      await out.finished;
+      if (over()) throw tooLarge();
+      const head = Buffer.alloc(8), tail = Buffer.alloc(4);
+      head.writeUInt32BE(out.size, 0); head.write('IDAT', 4, 'latin1'); tail.writeUInt32BE(out.crc >>> 0, 0);
+      const png = Buffer.concat([SIGNATURE, chunk('IHDR', ihdr({ width: first.width, height, colorType })), ...first.ancillary,
+        head, ...out.compressed, tail, chunk('IEND', Buffer.alloc(0))]);
+      if (png.length !== out.size + overhead) throw invalid();
+      return png;
+    },
+  };
+}
+
+/** Stitch every slice at once; the same output as adding them one by one. */
+export async function stitchPng(slices, options) {
+  if (!Array.isArray(slices) || !slices.length) throw invalid();
+  const stitcher = createPngStitcher(options);
+  for (const slice of slices) await stitcher.add(slice);
+  return stitcher.finish();
+}

package/dist/view-renderer/src/pool.js

@@ -0,0 +1,110 @@
+import { ViewRenderError } from './errors.js';
+
+export function browserEnvironment(environment = process.env) {
+  const names = ['PATH', 'HOME', 'TMPDIR', 'TEMP', 'TMP', 'LANG', 'SystemRoot', 'WINDIR', 'DISPLAY', 'XDG_RUNTIME_DIR'];
+  return Object.fromEntries(names.filter(name => typeof environment[name] === 'string').map(name => [name, environment[name]]));
+}
+
+/**
+ * A warm process, never a shared profile, cookie jar, localStorage or context.
+ * recycleAfter closes the browser once it has served that many renders and
+ * nothing is running or waiting, so a small host returns to its idle memory;
+ * the next render starts a fresh browser.
+ */
+export function createBrowserPool({ concurrency = 2, maxQueue = 8, recycleAfter = 0, launch = {}, chromium } = {}) {
+  if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > 4 || !Number.isInteger(maxQueue) || maxQueue < 0 || maxQueue > 32
+    || !Number.isInteger(recycleAfter) || recycleAfter < 0 || recycleAfter > 10000) throw new TypeError('Choose a bounded render pool.');
+  let browser, starting, retiring, closing = false, inUse = 0, served = 0, renders = 0;
+  const queue = new Set();
+  const contexts = new Set();
+  async function acquire(signal) {
+    if (closing || signal?.aborted) throw new ViewRenderError('render_cancelled', 'The render was cancelled.', 499);
+    if (inUse < concurrency) { inUse++; return; }
+    if (queue.size >= maxQueue) throw new ViewRenderError('render_busy', 'The renderer is busy. Try again shortly.', 503);
+    await new Promise((resolve, reject) => {
+      const entry = { resolve: () => { signal?.removeEventListener('abort', abort); resolve(); }, reject };
+      const abort = () => { queue.delete(entry); reject(new ViewRenderError('render_cancelled', 'The render was cancelled.', 499)); };
+      queue.add(entry); signal?.addEventListener('abort', abort, { once: true });
+    });
+  }
+  function release() {
+    const next = queue.values().next().value;
+    if (next) { queue.delete(next); next.resolve(); return; }
+    inUse--;
+    if (recycleAfter && served >= recycleAfter) retire();
+  }
+  function retire() {
+    if (inUse !== 0 || !browser || closing) return;
+    const old = browser;
+    browser = undefined; served = 0;
+    const done = old.close().catch(() => {}).then(() => { if (retiring === done) retiring = undefined; });
+    retiring = done;
+  }
+  async function getBrowser() {
+    if (browser?.isConnected()) return browser;
+    if (!starting) starting = (async () => {
+      // A retired browser has released its memory before the next one starts.
+      if (retiring) await retiring;
+      // Importing CLI command metadata never loads Playwright or starts Chrome.
+      const engine = chromium || (await import('playwright-core')).chromium;
+      const allowed = Object.fromEntries(['executablePath', 'channel', 'timeout'].filter(key => key in launch).map(key => [key, launch[key]]));
+      try {
+        browser = await engine.launch({ ...allowed, headless: true, chromiumSandbox: true,
+          env: browserEnvironment(), args: ['--force-webrtc-ip-handling-policy=disable_non_proxied_udp', '--disable-background-networking',
+            // A container's small /dev/shm cannot hold a tall page's shared memory.
+            '--disable-dev-shm-usage'] });
+      } catch (error) {
+        if (/Executable doesn't exist/.test(String(error?.message))) throw new ViewRenderError('render_browser_missing', 'Install the pinned Chromium browser with npx playwright-core@1.63.0 install chromium.', 503);
+        throw new ViewRenderError('render_browser_unavailable', 'Sandboxed Chromium could not start.', 503);
+      }
+      return browser;
+    })().finally(() => { starting = undefined; });
+    return starting;
+  }
+  return {
+    warm: () => getBrowser(),
+    /**
+     * Prove Chromium can start, failing like a render would when it cannot. A
+     * recycling pool closes the browser again at once, so an idle host keeps
+     * no browser; otherwise it stays warm for the first render.
+     */
+    async check() {
+      await getBrowser();
+      if (recycleAfter) retire();
+      if (retiring) await retiring;
+    },
+    async use(operation, { signal, width = 1440, locale = 'en', timezone = 'UTC' } = {}) {
+      await acquire(signal);
+      let context, launched = false;
+      const abort = () => { void context?.close(); };
+      try {
+        const browser = await getBrowser();
+        launched = true;
+        if (closing || signal?.aborted) throw new ViewRenderError('render_cancelled', 'The render was cancelled.', 499);
+        context = await browser.newContext({ viewport: { width, height: 900 }, deviceScaleFactor: 1,
+          locale, timezoneId: timezone, colorScheme: 'light', serviceWorkers: 'block', acceptDownloads: false, permissions: [] });
+        contexts.add(context); signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted) throw new ViewRenderError('render_cancelled', 'The render was cancelled.', 499);
+        return await operation(context);
+      } finally {
+        signal?.removeEventListener('abort', abort);
+        if (context) { contexts.delete(context); served++; renders++; await context.close().catch(() => {}); }
+        // A browser that failed to open a context still counts, so recycling closes it too.
+        else if (launched) served++;
+        release();
+      }
+    },
+    async close() {
+      closing = true;
+      for (const entry of queue) entry.reject(new ViewRenderError('render_cancelled', 'The renderer is stopping.', 503));
+      queue.clear();
+      await Promise.allSettled([...contexts].map(context => context.close()));
+      if (starting) await starting.catch(() => {});
+      await browser?.close();
+      if (retiring) await retiring;
+    },
+    // chromium: a browser may hold memory, from its launch until its close has finished.
+    stats: () => ({ active: inUse, queued: queue.size, contexts: contexts.size, warm: Boolean(browser?.isConnected()),
+      chromium: Boolean(starting || browser || retiring), renders }),
+  };
+}

package/dist/view-renderer/src/remote-broker.js

@@ -0,0 +1,59 @@
+import { ViewRenderError } from './errors.js';
+
+/** The purpose credential never enters request URLs, browser headers or source. */
+export function createRemoteRenderBroker({ apiBase, credential, fetcher = fetch }) {
+  const base = new URL(apiBase);
+  if (!['https:', 'http:'].includes(base.protocol) || (base.protocol === 'http:' && !['127.0.0.1', 'localhost', '[::1]'].includes(base.hostname))
+    || base.username || base.password || base.search || base.hash || typeof credential !== 'string' || !credential) throw new TypeError('Use a configured render API and its purpose credential.');
+  let claims;
+  try { claims = JSON.parse(Buffer.from(credential.split('.')[1], 'base64url').toString('utf8')); } catch {}
+  // This is rejection/identity checking only. Python performs cryptographic
+  // authentication and live authorization before returning any data.
+  if (claims?.type !== 'notis_view_render' || claims?.aud !== 'notis-view-render' || claims?.read_only !== true
+    || !claims?.jti || !claims?.target || typeof claims.url !== 'string') throw new ViewRenderError('render_credential_invalid', 'Use a dedicated read-only render credential, never a user JWT.', 401);
+  if (!Array.isArray(claims.outputs) || !claims.outputs.length || claims.outputs.some(value => !['markdown', 'screenshot'].includes(value))
+    || new Set(claims.outputs).size !== claims.outputs.length || ![390, 1440].includes(claims.width)) {
+    throw new ViewRenderError('render_credential_invalid', 'This credential does not pin render outputs.', 401);
+  }
+  const stable = value => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+    ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
+  const endpoint = path => new URL(`portal_view_render/${path}`, base.href.replace(/\/?$/, '/')).href;
+  async function request(operation, body, { signal } = {}) {
+    const response = await fetcher(endpoint(operation), { method: 'POST', redirect: 'error', credentials: 'omit', signal,
+      headers: { Authorization: `Bearer ${credential}`, 'Content-Type': 'application/json', 'X-Notis-Spaces-Protocol': '2' },
+      body: JSON.stringify(body) });
+    let result;
+    try { result = await response.json(); } catch { throw new ViewRenderError('render_broker_unavailable', 'The render read could not be confirmed.', 503); }
+    if (!response.ok) throw new ViewRenderError(typeof result?.error === 'string' ? result.error : 'render_unavailable', 'This view is unavailable for rendering.', response.status);
+    return result;
+  }
+  return Object.freeze({
+    snapshot: async options => {
+      const value = await request('read', { operation: 'manifest' }, options);
+      if (value?.url !== claims.url || value?.view?.space_id !== claims.target.space_id || value.view.revision !== claims.target.revision
+        || (value.record_key || null) !== (claims.target.record_key || null) || stable(value.params) !== stable(claims.target.params)
+        || value.descriptor?.space?.id !== claims.target.space_id || value.descriptor.space.revision !== claims.target.revision
+        || value.descriptor?.resource?.id !== claims.target.space_id || value.descriptor.resource.revision !== claims.target.revision
+        || stable(value.render_options) !== stable({ outputs: claims.outputs, width: claims.width })) {
+        throw new ViewRenderError('render_manifest_invalid', 'The render manifest belongs to another view.', 502);
+      }
+      return value;
+    },
+    read: (payload, options) => request('read', payload, options),
+    finish: async options => {
+      const value = await request('finish', {}, options);
+      if (value?.valid !== true || value.render_id !== claims.jti || value.url !== claims.url) {
+        throw new ViewRenderError('render_access_changed', 'The final render authority is not confirmed.', 403);
+      }
+      return value;
+    },
+    complete: async (rendered, options) => {
+      const value = await request('complete', { rendered }, options);
+      if (value?.valid !== true || value.render_id !== claims.jti || value.url !== claims.url) {
+        throw new ViewRenderError('render_capture_unconfirmed', 'The completed capture could not be recorded.', 409);
+      }
+      // Attestation/receipts remain backend-only even if an endpoint regresses.
+      return { valid: true, render_id: value.render_id, url: value.url };
+    },
+  });
+}