sign-off-axi 0.4.6 → 0.4.7

package/dist/cli.js

@@ -5,14 +5,15 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { spawn, spawnSync } from 'node:child_process';
 import { accessSync, closeSync, constants, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, watch, writeFileSync } from 'node:fs';
 import { lookup } from 'node:dns/promises';
-import { homedir, tmpdir, userInfo } from 'node:os';
+import { availableParallelism, homedir, tmpdir, userInfo } from 'node:os';
+import { Worker } from 'node:worker_threads';
 import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { parseArgs } from 'node:util';
 import { encode } from '@toon-format/toon';
 import { AxiError, runAxiCli } from 'axi-sdk-js';
 import { CHAPTERS_MAX, SIGNED_IN, CLEARED, InputError, MEDIA_MAX, NOTE_MAX, REPLY, answersPath, appendAnnotation, appendAnswer, appendDismissed, appendSendBack, appendDesignAnswer, appendMessage, appendRound, awaitsVerdict, isKey, loadDecisions, markDelivered, markSeen, messagesPath, readAnnotations, readAnswers, readDismissed, readItems, readMessages, readRounds, roundsPath, seenBy, seenPath, sentIds, unreadable as reasonOf, writeItems } from './store.js';
 import { ContractError, KINDS, MEDIA_BYTES, REPORT_INIT, checkMessage, mediaFiles, parseMessage, reportPage } from './contract.js';
-import { faults } from './evidence-text.js';
+import { faults, isStill } from './evidence-text.js';
 import { deliverVault, errors, readVaultExpiry, sweepVault, takeVaultExpiries, VaultError } from './vault.js';
 const FORMAT = 'https://github.com/umeranjum17/sign-off/blob/main/docs/file-formats.md';
 const CONTRACT = 'https://github.com/umeranjum17/sign-off/blob/main/docs/contract.md';
@@ -326,8 +327,10 @@ const ASK_FLAGS = ['why', 'outcome', 'recommend-reason', 'silent-by', 'merge'];
 const MANY = ['option', 'outcome', 'merge'];
 /** Board types that are contract kinds: a decision (the default type) is an ask. */
 const CONTRACT_TYPES = ['decision', 'ask', 'evidence', 'report', 'plan', 'design'];
-/** The stored item as the message it came from: the board's own `filed` stamp is not part of a message that names none. */
-const asSent = ({ filed: _filed, ...rest }) => rest;
+/** The stored item as the message it came from: the board's own `filed` stamp is not part of a message that names none, and the notice record (`announced`) is the board's too. */
+const asSent = ({ filed: _filed, announced: _announced, ...rest }) => rest;
+/** A report names its own `filed` time, so only the notice record goes. */
+const asReport = ({ announced: _announced, ...rest }) => rest;
 /** Items of a --from file that carry contract or kind are contract messages: each is checked against its kind's rules before anything is stored.
  * A new item of a contract kind must carry them (contract section 2). A --replace feed replaces the stored item, so an item under an existing key
  * that changed is checked again; an unchanged item, a board-format one and every item outside a --replace feed are not checked again. */
@@ -349,7 +352,7 @@ function contractItems(items, from, file, replace = false) {
         // item, a board-format one and every item outside a --replace feed are not checked again.
         const asMessage = (x) => {
             if (m?.kind !== 'evidence')
-                return m?.kind === 'report' ? x : asSent(x);
+                return m?.kind === 'report' ? asReport(x) : asSent(x);
             const { type: _type, number: _number, media, evidence: run, ...message } = asSent(x);
             return { ...message, ...(media !== undefined && { media: Array.isArray(media) ? media.map((r) => r?.path) : media }), ...(run && { run }) };
         };
@@ -919,7 +922,7 @@ function postSignin(file, named, on, values, filer) {
         let status = same ? (done ? 'already done' : 'already waiting') : had ? 'new link' : 'posted';
         if (!same) {
             fits(d.title, d.key);
-            const next = { ...item, filed: new Date().toISOString().replace(/\.\d+Z$/, 'Z') };
+            const next = { ...item, ...(had?.announced && { announced: had.announced }), filed: new Date().toISOString().replace(/\.\d+Z$/, 'Z') };
             if (had)
                 items[at] = next;
             else
@@ -990,7 +993,9 @@ function replace(file, named, on, from, filer) {
             }
         }
         const old = existsSync(file) ? readItems(file) : undefined;
-        let items = feed, extra = fed.extra, resulting = incoming;
+        // The notice record belongs to the card key, so a feed that rewrites a card keeps it: the receiver was told once.
+        const told = new Map((old?.items ?? []).filter((i) => i?.key && i.announced).map((i) => [i.key, i.announced]));
+        let items = feed.map((i) => (told.has(i?.key) ? { ...i, announced: told.get(i.key) } : i)), extra = fed.extra, resulting = incoming;
         if (filer) {
             // The feed's items first: the board shows the file's last item first, so the other filers' items keep showing on top.
             const fedKeys = new Set(feed.map((i) => i.key));
@@ -1067,7 +1072,7 @@ function postMedia(file, named, on, values, type, filer, message) {
         return path;
     });
     // A still that is not a picture of the product (text, colour bars or a placeholder) is measured before anything is copied.
-    const [unfit] = explainer ? [] : sources.flatMap((src) => /\.(png|jpe?g|webp)$/i.test(src) ? faults(src).map((f) => ({ src, f })) : []);
+    const [unfit] = explainer ? [] : sources.flatMap((src) => isStill(src) ? faults(src).map((f) => ({ src, f })) : []);
     if (unfit)
         throw fail(UNFIT[unfit.f](tilde(unfit.src)), 'VALIDATION_ERROR', 'Post a real capture of the running product instead: a screenshot or recording of the screen the user sees');
     mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
@@ -1077,8 +1082,8 @@ function postMedia(file, named, on, values, type, filer, message) {
         const current = board(file), store = join(dirname(file), 'evidence'), taken = current.map((d) => Number(/^update-(\d+)$/.exec(d.key)?.[1] ?? 0));
         const own = message ? message.key : explainer && (values.key ?? slug(values.title)), had = message && own && items.find((x) => x?.key === own);
         if (had) {
-            // The stored item, read back as the message it came from: its run, and each media file by hash.
-            const asMessage = ({ type: _t, number: _n, filed: _f, evidence: run, media: kept, ...rest }) => canon({ ...rest, run, media: kept?.map((x) => x.sha256) });
+            // The stored item, read back as the message it came from: its run, and each media file by hash. The notice record is the board's, not the message's.
+            const asMessage = ({ type: _t, number: _n, filed: _f, announced: _a, evidence: run, media: kept, ...rest }) => canon({ ...rest, run, media: kept?.map((x) => x.sha256) });
             if (asMessage(had) !== canon({ ...message, media: sources.length ? sources.map((src) => sha256(readFileSync(src))) : undefined })) {
                 throw fail(`key ${own} already holds a different message on ${tilde(file)}`, 'CONFLICT', 'Post it under a new key');
             }
@@ -1372,7 +1377,7 @@ function storeIncoming(file, named, on, { incoming, raw }, filer, exact = false)
             // The same question from another filer, or at another time, is the same question: it keeps its first filer and time.
             const same = (x) => JSON.stringify({ ...x, answer: undefined, dismissed: undefined, filer: undefined, filed: undefined, options: [...x.options].sort((a, b) => a.value.localeCompare(b.value)) });
             // A message that names no filed time matches the one the board stamped.
-            const differs = () => exact ? canon({ ...items.find((x) => x?.key === d.key), ...(raw[i].filed === undefined && { filed: undefined }) }) !== canon(raw[i]) : same(had) !== same(d);
+            const differs = () => exact ? canon({ ...items.find((x) => x?.key === d.key), ...(raw[i].filed === undefined && { filed: undefined }), announced: undefined }) !== canon(raw[i]) : same(had) !== same(d);
             if (had && differs())
                 throw refuse(`already holds a different ${contract ? 'message' : 'question'} on ${tilde(file)}`);
             // Each new item records when it was raised, unless it names its own time.
@@ -1674,13 +1679,23 @@ function waitingKeys(file) {
         return undefined;
     }
 }
-/** Announces each card that entered Waiting on you with a write. The card is already stored, so nothing here fails the command. */
+/** Announces each card that entered Waiting on you with a write. The card is already stored, so nothing here fails the command.
+ * A card is announced once: the card keeps the record, so one that leaves Waiting and comes back (a new sign-in link) stays quiet,
+ * the same silent return an Undo gets. */
 function notifyEntered(file, named, before) {
     try {
         const so = dirname(named), notify = before ? readSetup(so).notify : undefined;
         if (!before || !notify || (notify.token_env && !process.env[notify.token_env]))
             return;
-        for (const d of board(file, () => { }).filter((d) => waits(d) && !before.has(d.key)))
+        const { items } = readItems(file), fresh = board(file, () => { }).filter((d) => waits(d) && !before.has(d.key) && !items.some((i) => i?.key === d.key && i.announced));
+        if (!fresh.length)
+            return;
+        const at = new Date().toISOString().replace(/\.\d+Z$/, 'Z');
+        for (const i of items)
+            if (fresh.some((d) => d.key === i?.key))
+                i.announced = at;
+        writeItems(file, items);
+        for (const d of fresh)
             sendNotice(so, notify, d);
     }
     catch { }
@@ -1994,6 +2009,7 @@ async function serve(args) {
             tokenOf(parsed.file, true);
         await sweep('startup');
         [file, evidenceRoot] = [parsed.file, parsed.values['evidence-root'] ? resolve(parsed.values['evidence-root']) : ''];
+        guardReady = warmGuard();
         await new Promise((ok, no) => server.once('error', no).listen(port, bind, ok)).catch((e) => {
             throw fail(e.code === 'EADDRINUSE' ? `port ${port} is in use; pass --port` : e.code === 'EADDRNOTAVAIL' ? `${bind} is not an address of this machine; pass another --bind` : e.message, 'SERVE_FAILED', 'Run `sign-off-axi --help` for the flags, then start it again');
         });
@@ -2048,6 +2064,8 @@ async function exportBoard(args) {
     const parsed = parse('export', args, { out: { type: 'string' }, 'evidence-root': { type: 'string' } });
     ready(parsed.file, parsed.on, parsed.values['evidence-root']);
     [file, evidenceRoot] = [parsed.file, parsed.values['evidence-root'] ? resolve(parsed.values['evidence-root']) : ''];
+    guardReady = warmGuard();
+    await guardReady;
     const { file: _, messages: _messages, annotations: _annotations, ...frozen } = state(), files = {}, q = encodeURIComponent;
     let missing = 0;
     // The same URLs the page asks the server for, read through the same hash and path checks.
@@ -2094,18 +2112,75 @@ const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
 /** A card whose picture is a colour-bar test card or a placeholder is not shown: a card posted before the guard can hold one. Read by the
  * stored hash, so each picture is measured once. */
 const unfitMedia = new Map();
-const fakeEvidence = (d) => d.type === 'evidence' && (d.media ?? []).some((m) => {
-    if (!unfitMedia.has(m.sha256)) {
-        let found;
+const fakeEvidence = (d) => d.type === 'evidence' && (d.media ?? []).some((m) => isStill(m.path) && unfitMedia.get(m.sha256) === true);
+/** Every still on the board, once, so a request never walks the media: the board's files are hash-checked and immutable. */
+const stillJobs = () => {
+    const jobs = [], seen = new Set();
+    for (const d of loadDecisions(file)) {
+        if (d.type !== 'evidence')
+            continue;
+        for (const m of d.media ?? []) {
+            if (!isStill(m.path) || seen.has(m.sha256) || unfitMedia.has(m.sha256))
+                continue;
+            seen.add(m.sha256);
+            try {
+                jobs.push({ path: under(dirname(file), m.path), sha256: m.sha256 });
+            }
+            catch { /* an absent file has no faults */ }
+        }
+    }
+    return jobs;
+};
+/** Measures the board's stills in parallel and off the request path. A fresh board is therefore ready before it is asked for cards: the
+ * page and media answer at once, and the guard's pass never blocks them. One follow-up pass takes whatever a lost worker never reported. */
+let guardReady = Promise.resolve();
+/** A board read waits this long for the warm pass, so a still that is slow or stuck never holds the cards. */
+const GUARD_WAIT = 500;
+/** A worker still measuring after this is stuck in a convert that outlived its own timeout: it is stopped and its stills stay unmeasured. */
+const WORKER_WAIT = 35_000;
+const warmGuard = () => new Promise((done) => {
+    const pass = (retry) => {
+        let jobs;
         try {
-            found = faults(under(dirname(file), m.path)).some((f) => f !== 'text');
+            jobs = stillJobs();
         }
         catch {
-            return false;
+            return done();
+        }
+        if (!jobs.length)
+            return done();
+        const workers = Math.max(1, Math.min(8, availableParallelism(), jobs.length));
+        let left = workers;
+        const ended = () => {
+            if (--left)
+                return;
+            if (retry)
+                pass(false);
+            else
+                done();
+        };
+        for (let i = 0; i < workers; i++) {
+            let worker;
+            try {
+                worker = new Worker(new URL('./stills-worker.js', import.meta.url), { workerData: jobs.filter((_, j) => j % workers === i) });
+            }
+            catch {
+                ended();
+                continue;
+            }
+            let stop;
+            const arm = () => {
+                clearTimeout(stop);
+                stop = setTimeout(() => { void worker.terminate(); }, WORKER_WAIT);
+                stop.unref();
+            };
+            arm();
+            worker.on('message', ([sha, unfit]) => { unfitMedia.set(sha, unfit); arm(); });
+            worker.once('error', () => clearTimeout(stop));
+            worker.once('exit', () => { clearTimeout(stop); ended(); });
         }
-        unfitMedia.set(m.sha256, found);
-    }
-    return unfitMedia.get(m.sha256);
+    };
+    pass(true);
 });
 const state = () => {
     reap();
@@ -2292,6 +2367,9 @@ async function route(req) {
     if (req.method === 'GET' && req.url === '/api/board')
         return [200, { file, pid: process.pid }];
     if (req.method === 'GET' && req.url === '/api/decisions') {
+        let timer;
+        await Promise.race([guardReady, new Promise((ok) => { timer = setTimeout(ok, GUARD_WAIT); })]);
+        clearTimeout(timer);
         return [200, state()];
     }
     if (req.method !== 'POST' || !['/api/answers', '/api/rounds', '/api/messages', '/api/annotations', '/api/dismiss', '/api/signin'].includes(req.url ?? ''))

package/dist/evidence-text.js

@@ -1,4 +1,4 @@
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { inflateSync } from 'node:zlib';
 /** A picture of text (a log, receipt or summary) is a few colours: paper, ink and their anti-aliased blends, with no large flat block of a
@@ -26,12 +26,7 @@ const CHANNELS = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
 /** Adam7 interlace passes: x start, y start, x step, y step. A non-interlaced PNG is one pass over every pixel. */
 const ADAM7 = [[0, 0, 8, 8], [4, 0, 8, 8], [0, 4, 4, 8], [2, 0, 4, 4], [0, 2, 2, 4], [1, 0, 2, 2], [0, 1, 1, 2]];
 const WHOLE = [[0, 0, 1, 1]];
-/** The share of pixels that are ink (a colour off the paper), of pixels off the paper-ink line, and of the largest flat area in any other colour,
- * or undefined when the file cannot be decoded. */
-export function palette(file) {
-    const rgb = decode(file);
-    if (!rgb)
-        return undefined;
+const shareOf = (rgb) => {
     const total = rgb.length / 3, bins = new Uint32Array(32768);
     const centre = (b) => [(b >> 10) * 8 + 4, ((b >> 5) & 31) * 8 + 4, (b & 31) * 8 + 4];
     for (let i = 0; i < rgb.length; i += 3)
@@ -71,11 +66,19 @@ export function palette(file) {
             off++;
     }
     return { ink: ink / total, off: off / total, solid, top, bars, barShare };
+};
+export function palette(file) {
+    const rgb = decode(file);
+    return rgb && shareOf(rgb);
 }
+/** The still formats this guard measures. A recording is never measured: it is not a still, and decoding it would push a video through
+ * ImageMagick on every board load. */
+const STILL = /\.(png|jpe?g|webp)$/i;
+/** Whether the guard has a still to measure. Callers that scan a whole board use this to skip recordings, as post does. */
+export const isStill = (file) => STILL.test(file);
 /** Why a still is not a picture of the product: text (a log, receipt or summary), colour bars (a test card) or a placeholder (a flat card
- * standing in for a picture). A file that cannot be decoded has no faults: it is not refused. */
-export function faults(file) {
-    const share = palette(file);
+ * standing in for a picture). Anything that is not a still, and a file that cannot be decoded, has no faults: it is not refused. */
+function faultsOf(share) {
     if (!share)
         return [];
     const text = share.ink >= INK_MIN && share.off <= OFF_LINE_MAX && share.solid <= SOLID_MAX;
@@ -85,6 +88,17 @@ export function faults(file) {
         ...(!text && share.top >= PLACEHOLDER_MIN ? ['placeholder'] : []),
     ];
 }
+export function faults(file) {
+    if (!isStill(file))
+        return [];
+    return faultsOf(palette(file));
+}
+/** The same faults, decoded without blocking the caller's thread, so a hung child can be killed instead of holding a worker. */
+export async function faultsAsync(file) {
+    if (!isStill(file))
+        return [];
+    return faultsOf(await paletteAsync(file));
+}
 const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
 /** The picture as packed 8-bit RGB. PNG is decoded here; JPEG, WebP and any PNG this decoder refuses go through ImageMagick, when it is installed. */
 function decode(file) {
@@ -94,9 +108,51 @@ function decode(file) {
         if (own)
             return own;
     }
-    const out = spawnSync('convert', [file, 'png24:-'], { maxBuffer: 1 << 30, timeout: 30_000 });
+    const out = spawnSync('convert', [file, 'png24:-'], { maxBuffer: 1 << 30, timeout: 30_000, killSignal: 'SIGKILL' });
     return out.status === 0 && out.stdout.subarray(0, 8).equals(PNG_SIGNATURE) ? pngRgb(out.stdout) : undefined;
 }
+/** ImageMagick's output, bounded in time and size: the child, and anything it delegated to, is killed when either is passed. */
+async function paletteAsync(file) {
+    const bytes = readFileSync(file);
+    if (bytes.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        const own = pngRgb(bytes);
+        if (own)
+            return shareOf(own);
+    }
+    const out = await convert(file), rgb = out && out.subarray(0, 8).equals(PNG_SIGNATURE) ? pngRgb(out) : undefined;
+    return rgb && shareOf(rgb);
+}
+const CONVERT_WAIT = 30_000, CONVERT_BYTES = 1 << 30;
+function convert(file) {
+    return new Promise((done) => {
+        const child = spawn('convert', [file, 'png24:-'], { detached: true, stdio: ['ignore', 'pipe', 'ignore'] });
+        const chunks = [];
+        let finished = false, code = null, bytes = 0;
+        const finish = (out) => { if (!finished) {
+            finished = true;
+            clearTimeout(timer);
+            done(out);
+        } };
+        const stop = () => {
+            finish(undefined);
+            try {
+                process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+            child.stdout.destroy();
+        };
+        const timer = setTimeout(stop, CONVERT_WAIT);
+        child.stdout.on('data', (b) => { bytes += b.length; if (bytes > CONVERT_BYTES)
+            stop();
+        else
+            chunks.push(b); });
+        child.on('error', () => finish(undefined));
+        child.on('exit', (c) => { code = c; });
+        child.on('close', () => finish(code === 0 ? Buffer.concat(chunks) : undefined));
+    });
+}
 /** Packed 8-bit RGB of a PNG, every colour type and bit depth, interlaced or not. undefined for a PNG it does not read. */
 function pngRgb(buf) {
     try {

package/dist/stills-worker.js

@@ -0,0 +1,12 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { faultsAsync } from './evidence-text.js';
+/** One slice of a board's stills, measured off the server's thread so page and media requests keep answering. */
+const jobs = workerData;
+for (const { path, sha256 } of jobs) {
+    let unfit = false;
+    try {
+        unfit = (await faultsAsync(path)).some((f) => f !== 'text');
+    }
+    catch { /* an undecodable or unreadable still is not refused */ }
+    parentPort.postMessage([sha256, unfit]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sign-off-axi",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "One review board for evidence, quick yes/no decisions and retro changes.",
   "type": "module",
   "bin": { "sign-off-axi": "dist/cli.js" },

package/web/index.html

@@ -409,7 +409,8 @@
   .design-preview-full { display: block; max-width: 56rem; margin: 0 auto; color: var(--accent); }
   @media (min-width: 60rem) { .design-preview-window { max-width: 24.375rem; } }
   .design-review label { display: grid; gap: 0.5rem; max-width: 56rem; margin: 1rem auto; color: var(--muted); }
-  .design-review textarea { min-height: 6rem; padding: 0.75rem; background: var(--surface); }
+  /* The design note fills its column, so it lines up with the buttons under it at every width (the 70ch prose cap would narrow it at tablet width). */
+  .design-review textarea { max-width: none; min-height: 6rem; padding: 0.75rem; background: var(--surface); }
   .design-review .foot { max-width: 56rem; margin: 1rem auto; }
   .design-review .foot > * { flex: 1; }
   .design-review .foot button.open-link { background: var(--action); color: var(--on-accent); }
@@ -431,7 +432,7 @@
   .design-viewer-panel .foot { display: flex; gap: 0.75rem; margin: 0.5rem 0; }
   .design-viewer-panel .foot > * { flex: 1; }
   .design-viewer-panel label { display: grid; gap: 0.25rem; margin: 0.5rem 0; }
-  .design-viewer-panel textarea { min-height: 3rem; max-height: 6rem; margin: 0; }
+  .design-viewer-panel textarea { max-width: none; min-height: 3rem; max-height: 6rem; margin: 0; }
   .design-viewer-panel .open-link { background: var(--action); color: var(--on-accent); }
   @media (min-width: 60rem) { .design-viewer header h2 { font-size: 2.125rem; } .design-viewer-body { grid-template: minmax(0, 1fr) / minmax(0, 1fr) 22.5rem; } .design-viewer-panel { padding: 1.25rem; } }
   @media (max-height: 550px) { .design-viewer-body { overflow: auto; grid-template-rows: minmax(12rem, 1fr) auto; } }