@north-light/crouter 0.3.312 → 0.3.313

package/dist/clients/inbox/__tests__/integration/inbox-controller.test.js

@@ -1,81 +1,81 @@
+// The inbox controller against a real daemon: every row, page body, progress
+// autosave and settlement crosses the human/inbox routes, so this fixture binds
+// the daemon's own route tables rather than re-implementing their projections.
 import assert from 'node:assert/strict';
-import { createServer } from 'node:http';
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { ticketDir } from '#core/human/root';
-import { submitPage, takeoverAndCompletePage, writePageProgress } from '#core/human/tickets';
-import { InboxController } from '../../controller.js';
+import { startHumanDaemon } from '../../../__tests__/helpers/human-daemon.js';
+const daemon = await startHumanDaemon('crtr-inbox-controller');
+// Imported after the isolated home is in place, so nothing resolves the
+// developer's own canvas at module load.
+const { cliClient } = await import('#commands/api-client');
+const { InboxController } = await import('../../controller.js');
 const key = (part = {}) => ({ ctrl: false, meta: false, upArrow: false, downArrow: false, leftArrow: false, rightArrow: false, wordLeft: false, wordRight: false, home: false, end: false, pageUp: false, pageDown: false, del: false, return: false, newline: false, escape: false, tab: false, backspace: false, ...part });
 function fakeHost() {
     const handle = { close() { }, invalidate() { }, onClose() { } };
     return { capabilities: { remote: false, canFocusNode: false, selfPane: undefined }, mount: () => handle, notice() { }, suspendForChild: () => () => { }, focusNode: async () => false, pickReviewFile: async () => null };
 }
-const controller = (options = {}) => new InboxController({ host: fakeHost(), onDirty() { }, onClosed() { }, ...options });
-async function waitFor(predicate, message) { const end = Date.now() + 1000; while (!predicate()) {
+const controller = (cols, rows) => new InboxController({ host: fakeHost(), onDirty() { }, onClosed() { }, cols, rows });
+async function waitFor(predicate, message) { const end = Date.now() + 5000; for (;;) {
+    if (await predicate())
+        return;
     if (Date.now() > end)
         throw new Error(message);
     await new Promise((r) => setTimeout(r, 10));
 } }
-const temp = mkdtempSync(join(tmpdir(), 'crtr-inbox-controller-'));
-const sources = mkdtempSync(join(tmpdir(), 'crtr-page-sources-'));
-process.env['CRTR_HOME'] = temp;
-let received;
-async function startDaemon() {
-    const server = createServer(async (req, res) => {
-        if (!req.url?.endsWith('/resolve')) {
-            res.statusCode = 404;
-            res.end();
-            return;
-        }
-        const body = await new Promise((resolve) => { let text = ''; req.on('data', (c) => { text += c; }); req.on('end', () => resolve(text)); });
-        const nodeId = req.url.split('/').at(-2);
-        received = JSON.parse(body).responses;
-        takeoverAndCompletePage(ticketDir(nodeId), received, { host: 'daemon', pid: 1 });
-        res.end(JSON.stringify({ delivered: true, kind: 'page' }));
-    });
-    await new Promise((resolve) => server.listen(join(temp, 'crtrd.sock'), resolve));
-    return server;
-}
-const source = (name, body) => { const path = join(sources, name); writeFileSync(path, body); return path; };
-const ask = source('ask.tsx', 'export default () => (\n  <Page title="Restored page" subtitle="Pick one">\n    <UserQuestion id="choice" label="Restore?" body="Pick one to continue." mode="single" options={[{ id: "yes", label: "Yes" }, { id: "no", label: "No" }]} />\n  </Page>\n);\n');
-const rich = source('rich.tsx', 'export default () => (\n  <Page title="Rich page" subtitle="Browser content">\n    <Chart kind="bar" x="day" y={[{ field: "count" }]} />\n  </Page>\n);\n');
+const client = cliClient();
 // A ticket reaches the inbox and settles only with a response lifecycle; a page
 // carrying neither is a passive display that never opens here.
-const inboxDelivery = { placement: 'inline', inbox: true, reply: true };
-const server = await startDaemon();
+const delivery = { placement: 'inline', inbox: true, reply: false };
+const createPage = (source) => client.createHumanRequest({ page: { dialect: 'jsx', source }, delivery, creator_cwd: daemon.home });
+const ticketIdOf = async (requestId) => {
+    const { tickets } = await client.listHumanInbox();
+    const row = tickets.find((ticket) => ticket.request_id === requestId);
+    if (row === undefined)
+        throw new Error(`request is not listed in the inbox: ${requestId}`);
+    return row.ticket_id;
+};
+const ask = 'export default () => (\n  <Page title="Restored page" subtitle="Pick one">\n    <UserQuestion id="choice" label="Restore?" body="Pick one to continue." mode="single" options={[{ id: "yes", label: "Yes" }, { id: "no", label: "No" }]} />\n  </Page>\n);\n';
+const rich = 'export default () => (\n  <Page title="Rich page" subtitle="Browser content">\n    <Chart kind="bar" x="day" y={[{ field: "count" }]} />\n  </Page>\n);\n';
 try {
-    const ticket = submitPage({ dir: ticketDir('page-one'), sourceFile: ask, delivery: inboxDelivery });
-    writePageProgress(ticket.dir, { choice: { selectedOptionIds: ['yes'], comments: [] } });
-    const active = controller({ cols: 100, rows: 24 });
-    active.activate();
-    assert.equal(active.snapshot().screen, 'detail', 'page ticket opens in the page panel');
-    active.handleKey('n', key());
-    active.handleKey('', key({ return: true }));
-    await waitFor(() => existsSync(join(ticket.dir, 'response.json')), 'restored page responses cross the daemon seam');
-    assert.deepEqual(received, { choice: { selectedOptionIds: ['yes'], comments: [] } }, 'progress.json is restored into the response map');
-    active.close();
-    submitPage({ dir: ticketDir('rich-page'), sourceFile: rich, delivery: inboxDelivery });
-    const preview = controller({ cols: 100, rows: 24 });
+    // A page opens with the manifest-backed terminal projection of its content.
+    const richRequest = await createPage(rich);
+    const preview = controller(100, 24);
+    await waitFor(() => preview.snapshot().items.length === 1, 'the rich page reaches the inbox list');
+    preview.selectDir(richRequest.request_dir);
     assert.match(preview.render().join('\n'), /Rich page/, 'a pending page is listed before it is opened');
-    preview.activate();
+    await preview.activate();
     assert.match(preview.render().join('\n'), /chart — bar: day vs count/, 'a page uses the manifest-backed terminal projection');
     preview.close();
     // The list preview shows what the page says, because `s` settles the selected
-    // ticket from this screen without ever opening it.
-    submitPage({ dir: ticketDir('preview-page'), sourceFile: ask, delivery: inboxDelivery });
-    const listing = controller({ cols: 100, rows: 40 });
+    // ticket from this screen without ever opening it. The body is a round trip,
+    // so the first frame schedules it and a later frame carries it.
+    const previewRequest = await createPage(ask);
+    const listing = controller(100, 40);
+    await waitFor(() => listing.snapshot().items.length === 2, 'both pending pages reach the inbox list');
+    listing.selectDir(previewRequest.request_dir);
+    await waitFor(() => listing.render().join('\n').includes('Pick one to continue'), 'the preview carries the question body');
     const shown = listing.render().join('\n');
-    assert.match(shown, /Pick one to continue/, 'the preview carries the question body');
     assert.match(shown, /Yes/, 'the preview carries the options the reader would pick from');
     assert.doesNotMatch(shown, /\d+ components?\b/, 'the component count no longer stands in for the content');
     listing.close();
+    // Autosaved progress is restored into the page the reader opens, and the
+    // answer it submits crosses the daemon's settlement route.
+    const request = await createPage(ask);
+    await client.postInboxProgress(await ticketIdOf(request.request_id), { choice: { selectedOptionIds: ['yes'], comments: [] } });
+    const active = controller(100, 24);
+    await waitFor(() => active.snapshot().items.length === 3, 'the created page reaches the inbox list');
+    active.selectDir(request.request_dir);
+    await active.activate();
+    assert.equal(active.snapshot().screen, 'detail', 'page ticket opens in the page panel');
+    assert.match(active.render().join('\n'), /✓|\[✓\]/, 'the autosaved answer is restored into the open page');
+    active.handleKey('n', key());
+    active.handleKey('', key({ return: true }));
+    await waitFor(async () => (await client.getHumanRequest(request.request_id)).state !== 'pending', 'restored page responses cross the daemon seam');
+    const settled = await client.getHumanRequest(request.request_id);
+    assert.equal(settled.page?.result?.kind, 'page', 'the page settled with an answer');
+    assert.deepEqual(settled.page?.result?.kind === 'page' ? settled.page.result.responses : undefined, { choice: { selectedOptionIds: ['yes'], comments: [] } }, 'saved progress is restored into the response map');
+    active.close();
 }
 finally {
-    server.closeAllConnections();
-    await new Promise((resolve) => server.close(() => resolve()));
-    rmSync(temp, { recursive: true, force: true });
-    rmSync(sources, { recursive: true, force: true });
-    delete process.env['CRTR_HOME'];
+    await daemon.dispose();
 }
 console.log('inbox controller tests passed');

package/dist/clients/inbox/__tests__/integration/stale-row-activation.test.js

@@ -1,53 +1,66 @@
-// A page ticket that settles out-of-band (answered from another surface, or a
+// A page request that settles out-of-band (answered from another surface, or a
 // row this inbox failed to drop) must not read as "being edited by another
-// inbox" when the reader presses Enter: its response.json already exists, so the
-// row is stale and this activation must report the settlement and drop it.
+// inbox" when the reader presses Enter: its request row is already settled, so
+// the row is stale and this activation must report the settlement and drop it.
 import assert from 'node:assert/strict';
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { ticketDir } from '#core/human/root';
-import { submitPage, takeoverAndCompletePage } from '#core/human/tickets';
-import { claimPath } from '#core/human/convention';
-import { InboxController } from '../../controller.js';
+import { existsSync } from 'node:fs';
+import { startHumanDaemon } from '../../../__tests__/helpers/human-daemon.js';
+const daemon = await startHumanDaemon('crtr-stale-row');
+// Imported after the isolated home is in place, so nothing resolves the
+// developer's own canvas at module load.
+const { cliClient } = await import('#commands/api-client');
+const { withCanvasWrite } = await import('#core/canvas/db');
+const { settleRequestLocked } = await import('#core/human/requests');
+const { claimPath } = await import('#core/human/convention');
+const { InboxController } = await import('../../controller.js');
 const key = (part = {}) => ({ ctrl: false, meta: false, upArrow: false, downArrow: false, leftArrow: false, rightArrow: false, wordLeft: false, wordRight: false, home: false, end: false, pageUp: false, pageDown: false, del: false, return: false, newline: false, escape: false, tab: false, backspace: false, ...part });
 function fakeHost() {
     const handle = { close() { }, invalidate() { }, onClose() { } };
     return { capabilities: { remote: false, canFocusNode: false, selfPane: undefined }, mount: () => handle, notice() { }, suspendForChild: () => () => { }, focusNode: async () => false, pickReviewFile: async () => null };
 }
 const status = (c) => c.status;
-const temp = mkdtempSync(join(tmpdir(), 'crtr-stale-row-'));
-const sources = mkdtempSync(join(tmpdir(), 'crtr-stale-src-'));
-process.env['CRTR_HOME'] = temp;
-const sourceFile = join(sources, 'ask.tsx');
-writeFileSync(sourceFile, 'export default () => (\n  <Page title="Stale row page" subtitle="Pick one">\n    <UserQuestion id="choice" label="Restore?" body="Pick one." mode="single" options={[{ id: "yes", label: "Yes" }, { id: "no", label: "No" }]} />\n  </Page>\n);\n');
-const inboxDelivery = { placement: 'inline', inbox: true, reply: true };
+async function waitFor(predicate, message) { const end = Date.now() + 5000; while (!predicate()) {
+    if (Date.now() > end)
+        throw new Error(message);
+    await new Promise((r) => setTimeout(r, 10));
+} }
 try {
-    const dir = ticketDir('stale-page');
-    submitPage({ dir, sourceFile, delivery: inboxDelivery });
-    // Seed the controller's in-memory list from disk while the ticket is pending.
-    const options = { cols: 100, rows: 24 };
-    const controller = new InboxController({ host: fakeHost(), onDirty() { }, onClosed() { }, ...options });
-    assert.equal(controller.snapshot().items.length, 1, 'pending page is listed');
-    // Settle it out of band, without letting the controller rescan: this is the
-    // stale-row state the bug leaves behind.
-    takeoverAndCompletePage(dir, { choice: { selectedOptionIds: ['yes'], comments: [] } }, { host: 'daemon', pid: 1 });
-    assert.equal(existsSync(join(dir, 'response.json')), true, 'response is published on disk');
-    assert.equal(existsSync(claimPath(dir)), false, 'completion leaves no claim behind');
+    const client = cliClient();
+    const request = await client.createHumanRequest({
+        page: { dialect: 'jsx', source: 'export default () => (\n  <Page title="Stale row page" subtitle="Pick one">\n    <UserQuestion id="choice" label="Restore?" body="Pick one." mode="single" options={[{ id: "yes", label: "Yes" }, { id: "no", label: "No" }]} />\n  </Page>\n);\n' },
+        delivery: { placement: 'inline', inbox: true, reply: false },
+        creator_cwd: daemon.home,
+    });
+    // Seed the controller's in-memory list while the request is open.
+    const controller = new InboxController({ host: fakeHost(), onDirty() { }, onClosed() { }, cols: 100, rows: 24 });
+    await waitFor(() => controller.snapshot().items.length === 1, 'pending page is listed');
+    // Settle it in the canvas without letting the controller rescan: this is the
+    // stale-row state the bug leaves behind, and it stands for a settlement some
+    // other surface performed.
+    const settledAt = new Date().toISOString();
+    const settled = withCanvasWrite((db) => settleRequestLocked(db, {
+        request_id: request.request_id,
+        outcome: 'answered',
+        result_json: JSON.stringify({ schema: 'crtr.page-response/v1', kind: 'page', responses: { choice: { selectedOptionIds: ['yes'], comments: [] } }, summary: 'page submitted', completedAt: settledAt }),
+        settled_at: settledAt,
+    }));
+    assert.notEqual(settled, null, 'the out-of-band settlement wins the terminal transition');
+    assert.equal((await client.getHumanRequest(request.request_id)).state, 'answered', 'the request row is terminal');
+    assert.equal(existsSync(claimPath(request.request_dir)), false, 'settlement leaves no claim behind');
     assert.equal(controller.snapshot().items.length, 1, 'the in-memory row is still stale');
     // Pressing Enter on the stale row must report the settlement and drop it,
-    // never claim it is edited by another inbox.
+    // never claim it is edited by another inbox. A claim would still succeed on
+    // the directory, so the settled row is recognized from its request record.
     controller.handleKey('', key({ return: true }));
+    await waitFor(() => controller.snapshot().items.length === 0, 'the stale row drops on activation');
     const reported = status(controller) ?? '';
     assert.match(reported, /already resolved/, `stale-row activation reports the settlement, got: ${JSON.stringify(reported)}`);
     assert.doesNotMatch(reported, /being edited/, 'a settled row is never "edited by another inbox"');
-    assert.equal(controller.snapshot().items.length, 0, 'the stale row drops on activation');
     assert.equal(controller.snapshot().screen, 'list', 'a settled row never opens the detail pane');
+    assert.equal(existsSync(claimPath(request.request_dir)), false, 'a stale row is never claimed');
     controller.close();
     console.log('stale-row regression passed');
 }
 finally {
-    rmSync(temp, { recursive: true, force: true });
-    rmSync(sources, { recursive: true, force: true });
-    delete process.env['CRTR_HOME'];
+    await daemon.dispose();
 }

package/dist/clients/inbox/controller.d.ts

@@ -1,6 +1,6 @@
-import type { TicketSummary } from '../../core/human/types.js';
 import type { Key } from './tui/keys.js';
 import type { SurfaceHost } from '../surfaces/host.js';
+import type { InboxRow } from './dto-adapt.js';
 export interface InboxControllerOptions {
     host: SurfaceHost;
     /** Called whenever the rendered frame may have changed. */
@@ -9,8 +9,8 @@ export interface InboxControllerOptions {
     onClosed: () => void;
     cols?: number;
     rows?: number;
-    scan?: () => TicketSummary[];
-    /** Replaces the default synchronous rescan after inbox activity. */
+    scan?: () => Promise<InboxRow[]>;
+    /** Replaces the default rescan after inbox activity. */
     onInboxActivity?: () => void;
     /** Ticket dir to seat the selection on at construction, when present. */
     initialSelection?: string;
@@ -39,19 +39,31 @@ export declare class InboxController {
     private heartbeat;
     private started;
     private closed;
-    /** The selected page's projected body, kept across frames because building it
-     *  reads and evaluates the page document. Keyed by what changes it. */
+    /** The selected page's projection, kept across frames because fetching it is
+     *  a round trip. `view` is held so a width change re-wraps without one. */
     private preview;
+    /** A preview read that failed, so the panel says so instead of staying blank. */
+    private previewFailed;
+    /** In-flight preview fetch, keyed by dir: one request per selection at a time. */
+    private previewFetching;
+    /** Set by `invalidate`: the held preview may no longer be the current revision. */
+    private previewStale;
+    /** The revision the open detail was loaded from, so a replacement published
+     *  while the reader has the page open reloads it. */
+    private openRevision;
     constructor(options: InboxControllerOptions);
     snapshot(): {
-        items: TicketSummary[];
+        items: InboxRow[];
         selectedDir?: string;
         screen: Screen;
         inputBuffer?: string;
     };
-    rescan(): void;
+    rescan(): Promise<void>;
     start(): void;
-    invalidate(): void;
+    /** Inbox activity is the one signal a replacement always emits, and it is
+     *  emitted after the new revision is selected — so an open page reloads here
+     *  rather than from a file watch that cannot see a directory swap. */
+    invalidate(): Promise<void>;
     resize(cols: number, rows: number): void;
     render(): string[];
     handleKey(input: string, key: Key): void;
@@ -60,12 +72,15 @@ export declare class InboxController {
      *  row without a fast action says so rather than opening the page: the key
      *  means one thing, and the page is what Enter is for. */
     private sendFastAction;
+    /** A review and a page are two different durable records; the inbox dismisses
+     *  whichever one the selected row actually is. */
     private cancelFromInbox;
-    activate(): void;
+    activate(): Promise<void>;
     private activateReview;
     /** Seat the selection on a ticket dir, when present in the current list. */
     selectDir(dir: string): void;
-    reloadSelectedPage(): void;
+    /** Re-read the open page and reload it only when its revision actually moved. */
+    reloadSelectedPage(): Promise<void>;
     close(): void;
     private complete;
     /** Edit the active buffer while the host releases the terminal to $EDITOR. */
@@ -75,12 +90,22 @@ export declare class InboxController {
     private detailSize;
     private detailLines;
     private focusAvailable;
-    /** Ask the host to bring the selected ticket's node viewer into view. */
+    /** Ask the host to bring the requesting node's viewer into view — the
+     *  conversation that raised this ask. */
     private focusSelectedSource;
-    /** What the selected page actually says, projected once per document and
-     *  kept until the document, the selection, or the pane width changes — the
-     *  projection reads the ticket from disk and evaluates it. */
+    /** What the selected page actually says. Rendering is synchronous and the
+     *  page is a round trip, so the projection is held and a miss schedules the
+     *  fetch, marking the frame dirty when it lands. A width change re-wraps the
+     *  held projection without another read. */
     private pagePreviewBody;
+    /** One in-flight preview read at a time. A revision that did not move keeps
+     *  the held projection, so activity on an unrelated ticket costs no re-wrap. */
+    private schedulePreview;
+    /** The request record is the settlement authority: a settled page publishes
+     *  no file, so a claim would still succeed on its directory. An unreachable
+     *  daemon reads as "not known to be settled" — the settle attempt that
+     *  follows is the one that fails loudly. */
+    private requestOrNull;
     /** The read-only preview beside the list. It shows the page's own content,
      *  because `s` settles the selected ticket from here without ever opening
      *  it — a reader must not answer something they were never shown. */
@@ -88,6 +113,9 @@ export declare class InboxController {
     private withStatus;
     private markDirty;
     private watchRoots;
+    /** The request directory still carries the claim and progress files other
+     *  inboxes write. Its page content lives in the daemon-selected revision,
+     *  which `invalidate` re-reads over the API. */
     private watchSelected;
 }
 export {};