@celilo/cli 0.15.0 → 0.16.2

package/src/services/alerting/inbound-poller.test.ts

@@ -118,6 +118,7 @@ describe('pollInbound', () => {
     });
 
   const alertState = () => db.select().from(alerts).where(eq(alerts.id, 'alert-1')).get()?.state;
+  const ackedBy = () => db.select().from(alerts).where(eq(alerts.id, 'alert-1')).get()?.ackedBy;
 
   test('only transports with routes are polled', () => {
     expect(transportsWithRoutes(db)).toEqual(['signal']);
@@ -326,9 +327,199 @@ describe('pollInbound', () => {
     expect(alertState()).toBe('firing');
   });
 
+  // The seam that was untested. `acknowledgeAlert` returning null was covered
+  // (ack.test.ts), and pollInbound was covered — but not what the REPORT says
+  // when the two meet. Observed live: a reply produced `1 acked` while every
+  // alert still read `ackedBy: null`, because the counter incremented next to
+  // the call instead of observing its result.
+  describe('a token whose alert no longer exists', () => {
+    test('is NOT counted as acked', async () => {
+      const delivery = page(peterRoute.id);
+      db.delete(alerts).run(); // the alert this token names is gone
+
+      const report = await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+
+      expect(report.acked).toBe(0);
+    });
+
+    test('is reported as stale_target rather than silently', async () => {
+      const delivery = page(peterRoute.id);
+      db.delete(alerts).run();
+
+      const report = await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+
+      expect(report.unheard).toEqual([{ senderAddress: PETER, reason: 'stale_target' }]);
+    });
+
+    // The token is still single-use: a dead target must not leave it replayable.
+    test('still consumes the token', async () => {
+      const delivery = page(peterRoute.id);
+      db.delete(alerts).run();
+
+      await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+      const second = await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+
+      expect(second.acked).toBe(0);
+      expect(second.unheard).toEqual([{ senderAddress: PETER, reason: 'unknown_token' }]);
+    });
+
+    // Nobody should be told "someone took it" when nobody did.
+    test('broadcasts nothing', async () => {
+      const delivery = page(peterRoute.id);
+      db.delete(alerts).run();
+
+      const report = await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+
+      expect(report.broadcast).toBe(0);
+    });
+  });
+
+  // The counter must track the database, not the attempt. If these two ever
+  // disagree again, the operator sees a success that did not happen.
+  test('report.acked agrees with what the alert row actually says', async () => {
+    const delivery = page(peterRoute.id);
+
+    const report = await pollInbound(db, deps([inbound(PETER, delivery.token)]));
+
+    expect(report.acked).toBe(1);
+    expect(alertState()).toBe('acked');
+    expect(ackedBy()).toBe(peterRoute.personId);
+  });
+
   test('a route pointing at a transport nobody uses is not polled', () => {
     db.delete(alerts).run();
     expect(transportsWithRoutes(db)).toEqual(['signal']);
     expect(wifeRoute.transportModuleId).toBe('signal');
   });
+
+  /**
+   * Answering a deploy question, at the SEAM.
+   *
+   * This is the coverage #533 was missing. `parseInterviewAnswer` was unit
+   * tested and correct; `pollInbound` was unit tested and correct; and an
+   * answer sent in the shape the page asks for was rejected as `unrecognised`
+   * for months, because nothing exercised an interview delivery THROUGH the
+   * poller. Two green units, wrong wiring — the same shape as the ack counter
+   * above.
+   */
+  describe('an answer to a deploy question', () => {
+    const ask = (routeId: string, eventId = '42') =>
+      mintDelivery(db, {
+        kind: 'interview',
+        targetId: eventId,
+        routeId,
+        now: NOW,
+        ttlMs: 60_000,
+      });
+
+    test('is published against the waiting question and counted as answered', async () => {
+      const question = ask(peterRoute.id, '42');
+      const answered: { eventId: string; value: string }[] = [];
+
+      const report = await pollInbound(
+        db,
+        deps([inbound(PETER, `${question.token} admin@example.org`)], {
+          answerInterview: (eventId, value) => answered.push({ eventId, value }),
+        }),
+      );
+
+      expect(answered).toEqual([{ eventId: '42', value: 'admin@example.org' }]);
+      expect(report.answered).toBe(1);
+      // An answer is not an acknowledgement; nothing about an alert moved.
+      expect(report.acked).toBe(0);
+      expect(report.unheard).toEqual([]);
+    });
+
+    test('a value containing spaces survives verbatim', async () => {
+      const question = ask(peterRoute.id);
+      const answered: string[] = [];
+
+      await pollInbound(
+        db,
+        deps([inbound(PETER, `${question.token} my value: with, punctuation`)], {
+          answerInterview: (_id, value) => answered.push(value),
+        }),
+      );
+
+      expect(answered).toEqual(['my value: with, punctuation']);
+    });
+
+    test('the token is consumed, so an answer cannot be replayed', async () => {
+      const question = ask(peterRoute.id);
+      const answered: string[] = [];
+      const withResponder = (body: string) =>
+        pollInbound(
+          db,
+          deps([inbound(PETER, body)], { answerInterview: (_id, v) => answered.push(v) }),
+        );
+
+      await withResponder(`${question.token} first`);
+      const second = await withResponder(`${question.token} second`);
+
+      expect(answered).toEqual(['first']);
+      expect(second.answered).toBe(0);
+      // `unrecognised`, not `unknown_token`: once the token no longer resolves,
+      // `<word> <text>` is indistinguishable from an ordinary sentence, so
+      // celilo declines to assert the operator mistyped a token.
+      expect(second.unheard).toEqual([{ senderAddress: PETER, reason: 'unrecognised' }]);
+    });
+
+    // Naming the question but supplying nothing is its own answer, and the
+    // token must survive so the operator's next attempt can work.
+    test('a token with no value reports needs_value and leaves the token live', async () => {
+      const question = ask(peterRoute.id);
+
+      const first = await pollInbound(
+        db,
+        deps([inbound(PETER, question.token)], { answerInterview: () => {} }),
+      );
+      expect(first.answered).toBe(0);
+      expect(first.unheard).toEqual([{ senderAddress: PETER, reason: 'needs_value' }]);
+
+      const answered: string[] = [];
+      const second = await pollInbound(
+        db,
+        deps([inbound(PETER, `${question.token} admin@example.org`)], {
+          answerInterview: (_id, v) => answered.push(v),
+        }),
+      );
+      expect(second.answered).toBe(1);
+      expect(answered).toEqual(['admin@example.org']);
+    });
+
+    // With no responder attached there is nothing to publish against, so the
+    // question stays unanswered AND the token stays usable.
+    test('with no responder attached the token is not burned', async () => {
+      const question = ask(peterRoute.id);
+
+      const report = await pollInbound(db, deps([inbound(PETER, `${question.token} value`)]));
+      expect(report.answered).toBe(0);
+      expect(report.unheard).toEqual([{ senderAddress: PETER, reason: 'unrecognised' }]);
+
+      const answered: string[] = [];
+      const retry = await pollInbound(
+        db,
+        deps([inbound(PETER, `${question.token} value`)], {
+          answerInterview: (_id, v) => answered.push(v),
+        }),
+      );
+      expect(retry.answered).toBe(1);
+      expect(answered).toEqual(['value']);
+    });
+
+    test('an answer from a number the question was not sent to is refused', async () => {
+      const question = ask(peterRoute.id);
+      const answered: string[] = [];
+
+      const report = await pollInbound(
+        db,
+        deps([inbound(WIFE, `${question.token} admin@example.org`)], {
+          answerInterview: (_id, v) => answered.push(v),
+        }),
+      );
+
+      expect(answered).toEqual([]);
+      expect(report.unheard).toEqual([{ senderAddress: WIFE, reason: 'wrong_sender' }]);
+    });
+  });
 });

package/src/services/alerting/inbound-poller.ts

@@ -20,7 +20,6 @@ import { loadCapabilityFunctions } from '../../hooks/capability-loader';
 import { createCapturingLogger } from '../../hooks/logger';
 import { type AckResult, acknowledgeAlert } from './ack';
 import { interpretInbound } from './inbound';
-import { parseInterviewAnswer } from './interview-responder';
 import type { NotificationTransport } from './notifier';
 import { composeAckBroadcastBody } from './notifier';
 import { consumeDelivery } from './tokens';
@@ -48,7 +47,16 @@ export interface TransportFailure {
 /** A message that was read but not acted on, and why. */
 export interface UnheardMessage {
   senderAddress: string;
-  reason: 'unknown_sender' | 'unknown_token' | 'wrong_sender' | 'ambiguous' | 'unrecognised';
+  reason:
+    | 'unknown_sender'
+    | 'unknown_token'
+    | 'wrong_sender'
+    | 'ambiguous'
+    | 'unrecognised'
+    /** A deploy question was named, but with no value to answer it with. */
+    | 'needs_value'
+    /** The token was valid, but the alert it names no longer exists. */
+    | 'stale_target';
 }
 
 export interface InboundPollDeps {
@@ -150,14 +158,19 @@ export async function pollInbound(db: DbClient, deps: InboundPollDeps): Promise<
 
       // An interview reply IS the answer rather than an acknowledgement —
       // same token table, same sender check, different meaning for the body.
-      if (outcome.delivery.kind === 'interview') {
-        const value = parseInterviewAnswer(message.body, outcome.delivery.token);
-        if (!value || !deps.answerInterview) {
+      // The value was extracted by `interpretInbound`, which is the only place
+      // that knows the delivery's kind; re-parsing it here is what left the
+      // real grammar unreachable for months (#533).
+      if (outcome.action === 'answer') {
+        if (!deps.answerInterview) {
+          // Nothing is attached to publish the answer against, so the question
+          // is still unanswered. Say so rather than consuming the token: the
+          // operator's next attempt has to be able to work.
           report.unheard.push({ senderAddress: message.senderAddress, reason: 'unrecognised' });
           continue;
         }
         consumeDelivery(db, outcome.delivery.id, deps.now());
-        deps.answerInterview(outcome.delivery.targetId, value);
+        deps.answerInterview(outcome.delivery.targetId, outcome.value);
         report.answered++;
         continue;
       }
@@ -171,12 +184,23 @@ export async function pollInbound(db: DbClient, deps: InboundPollDeps): Promise<
         outcome.route.personId,
         deps.now(),
       );
+
+      // A live token can outlive the alert it names. When the row is gone
+      // there is nothing to acknowledge, and saying "1 acked" anyway is a lie
+      // the operator has no way to catch — observed live: a reply reported
+      // `1 acked` while every alert still read `ackedBy: null`. Count what
+      // HAPPENED, never what was attempted.
+      if (!ack) {
+        report.unheard.push({ senderAddress: message.senderAddress, reason: 'stale_target' });
+        continue;
+      }
+
       report.acked++;
 
       // Everyone else who was paged is still expecting to act. Telling them is
       // the entire point of a per-delivery token — it is what makes the reply
       // identify a PERSON rather than just an alert.
-      if (ack) report.broadcast += await broadcastAck(db, ack, deps);
+      report.broadcast += await broadcastAck(db, ack, deps);
     }
 
     deps.writeCursor(transportId, received.cursor);

package/src/services/alerting/inbound.test.ts

@@ -33,8 +33,37 @@ describe('parseInbound', () => {
     expect(parseInbound('K7QM2X ack')).toEqual({ kind: 'ack', token: 'K7QM2X' });
   });
 
-  test.each(['', '   ', 'what is going on', 'K7QM', 'K7QM2XY'])('%p is unrecognised', (body) => {
-    expect(parseInbound(body)).toEqual({ kind: 'unrecognised' });
+  test.each(['', '   ', 'what is going on', 'K7QM2XY', 'ack now please'])(
+    '%p is unrecognised',
+    (body) => {
+      expect(parseInbound(body)).toEqual({ kind: 'unrecognised' });
+    },
+  );
+
+  // The bug that started this: the page says "reply BPRJEH", and a human types
+  // "ack BPRJEH". The old grammar read the VERB as the token, failed the length
+  // check, and rejected a real acknowledgement over word order.
+  test.each([
+    ['ack K7QM2X', 'K7QM2X'],
+    ['ACK K7QM2X', 'K7QM2X'],
+    ['ok k7qm2x', 'K7QM2X'],
+    ['K7QM2X ack', 'K7QM2X'],
+    ['k7qm2x OK', 'K7QM2X'],
+    ['👍 K7QM2X', 'K7QM2X'],
+    ['  ack   k7qm2x  ', 'K7QM2X'],
+  ])('%p yields token %p — the verb may lead, trail, or be absent', (body, token) => {
+    expect(parseInbound(body)).toEqual({ kind: 'ack', token });
+  });
+
+  // A prefix is legal INPUT; whether it identifies anything is the delivery
+  // table's question, not the parser's.
+  test.each([
+    ['bp', 'BP'],
+    ['ack bp', 'BP'],
+    ['BP ack', 'BP'],
+    ['b', 'B'],
+  ])('%p parses as the prefix %p', (body, token) => {
+    expect(parseInbound(body)).toEqual({ kind: 'ack', token });
   });
 });
 
@@ -128,6 +157,69 @@ describe('interpretInbound', () => {
     expect(interpretInbound(db, late)).toEqual({ action: 'rejected', reason: 'unknown_token' });
   });
 
+  describe('an abbreviated token', () => {
+    // How much an operator must type depends on what is actually outstanding.
+    test('resolves when the prefix is unique among live deliveries', () => {
+      const delivery = mintFor('r-peter');
+      const prefix = delivery.token.slice(0, 2);
+      const outcome = interpretInbound(db, context(PETER, `ack ${prefix.toLowerCase()}`));
+      expect(outcome).toMatchObject({ action: 'ack' });
+      expect(outcome.action === 'ack' && outcome.delivery.id).toBe(delivery.id);
+    });
+
+    test('a single character is enough when only one alert is live', () => {
+      const delivery = mintFor('r-peter');
+      // One character in 32 is `K`, which is ALSO an ack synonym — so that
+      // token parses as a bare ack rather than as a prefix. Either reading
+      // must land on the single live delivery, so the harness reflects it as
+      // outstanding as well; without this the test failed ~3% of runs with
+      // `unknown_token`, because the bare-ack path saw nothing outstanding.
+      outstanding.push(delivery);
+      const outcome = interpretInbound(db, context(PETER, delivery.token.slice(0, 1)));
+      expect(outcome).toMatchObject({ action: 'ack' });
+    });
+
+    // Never a guess: acknowledging the wrong alert is worse than asking again.
+    test('is refused as ambiguous when two live deliveries share the prefix', () => {
+      const a = mintFor('r-peter', 'alert-a');
+      let b = mintFor('r-peter', 'alert-b');
+      // Force a shared prefix rather than hoping two random tokens collide.
+      for (let i = 0; i < 40 && b.token[0] !== a.token[0]; i++) {
+        b = mintFor('r-peter', `alert-b-${i}`);
+      }
+      if (b.token[0] !== a.token[0]) return; // vanishingly unlikely; do not flake
+      // As above: a shared first character of `K` parses as a bare ack, and
+      // that path reads `outstandingForRoute` rather than the prefix search.
+      // Both readings must answer `ambiguous` here, so both are given two
+      // candidates to be ambiguous between.
+      outstanding.push(a, b);
+      expect(interpretInbound(db, context(PETER, a.token[0]))).toEqual({
+        action: 'rejected',
+        reason: 'ambiguous',
+      });
+    });
+
+    // Uniqueness is scoped to what is LIVE, so yesterday's tokens cannot make
+    // today's prefix ambiguous.
+    test('an expired delivery does not make a prefix ambiguous', () => {
+      const delivery = mintFor('r-peter');
+      const late = {
+        ...context(PETER, delivery.token.slice(0, 2)),
+        now: new Date(NOW.getTime() + TTL_MS + 1),
+      };
+      expect(interpretInbound(db, late)).toEqual({ action: 'rejected', reason: 'unknown_token' });
+    });
+
+    // The second factor still holds for a prefix.
+    test('a prefix from the WRONG sender is still refused', () => {
+      const delivery = mintFor('r-peter');
+      expect(interpretInbound(db, context(WIFE, delivery.token.slice(0, 3)))).toEqual({
+        action: 'rejected',
+        reason: 'wrong_sender',
+      });
+    });
+  });
+
   test('gibberish from a known sender is rejected as unrecognised', () => {
     expect(interpretInbound(db, context(PETER, 'what is going on'))).toEqual({
       action: 'rejected',
@@ -168,6 +260,125 @@ describe('interpretInbound', () => {
       });
     });
   });
+
+  /**
+   * Answering a deploy question.
+   *
+   * These ran against `parseInterviewAnswer` in isolation and all passed while
+   * the feature was dead in production (#533) — the alert grammar rejected
+   * every one of these bodies before the answer path was ever reached. They
+   * live here now, against `interpretInbound`, because the wiring is the part
+   * that was broken and the part worth guarding.
+   */
+  describe('a deploy question', () => {
+    const askFor = (routeId: string, targetId = 'evt-1') =>
+      mintDelivery(db, { kind: 'interview', targetId, routeId, now: NOW, ttlMs: TTL_MS });
+
+    test('takes everything after the token as the answer', () => {
+      const q = askFor('r-peter');
+      expect(interpretInbound(db, context(PETER, `${q.token} www.example.com`))).toMatchObject({
+        action: 'answer',
+        value: 'www.example.com',
+      });
+    });
+
+    test('is case-insensitive on the token', () => {
+      const q = askFor('r-peter');
+      expect(
+        interpretInbound(db, context(PETER, `${q.token.toLowerCase()} www.example.com`)),
+      ).toMatchObject({ action: 'answer', value: 'www.example.com' });
+    });
+
+    // An answer may legitimately contain spaces and punctuation. Second-guessing
+    // it would corrupt exactly the values that are painful to retype. This is
+    // the shape that was refused as `unrecognised` for months.
+    test('preserves an answer containing spaces and punctuation verbatim', () => {
+      const q = askFor('r-peter');
+      expect(
+        interpretInbound(db, context(PETER, `${q.token} my value: with, punctuation`)),
+      ).toMatchObject({ action: 'answer', value: 'my value: with, punctuation' });
+    });
+
+    // The word that must NOT acknowledge an alert is a perfectly good answer to
+    // a question. That the same text means different things is the whole reason
+    // the token is resolved before the grammar is chosen.
+    test('an answer that looks like a terminal verb is still an answer', () => {
+      const q = askFor('r-peter');
+      expect(interpretInbound(db, context(PETER, `${q.token} resolve`))).toMatchObject({
+        action: 'answer',
+        value: 'resolve',
+      });
+    });
+
+    test('a token with no value says so, rather than being unrecognised', () => {
+      const q = askFor('r-peter');
+      for (const body of [q.token, `${q.token}   `]) {
+        expect(interpretInbound(db, context(PETER, body))).toEqual({
+          action: 'rejected',
+          reason: 'needs_value',
+        });
+      }
+    });
+
+    // A verb-led message names no value, so it is not an answer.
+    test('a leading ack verb is not an answer', () => {
+      const q = askFor('r-peter');
+      expect(interpretInbound(db, context(PETER, `ack ${q.token}`))).toEqual({
+        action: 'rejected',
+        reason: 'unrecognised',
+      });
+    });
+
+    // Both factors still apply — a question is no less sensitive than a page.
+    test('an answer from the wrong number is refused', () => {
+      const q = askFor('r-peter');
+      expect(interpretInbound(db, context(WIFE, `${q.token} www.example.com`))).toEqual({
+        action: 'rejected',
+        reason: 'wrong_sender',
+      });
+    });
+
+    // Reported as `unrecognised` rather than `unknown_token`, and that is
+    // deliberate: `ZZZZZZ value` and `what is going on` are the same shape to
+    // celilo — a token-shaped word followed by text — because the token
+    // alphabet is most of the Latin one. Nothing corroborates that the leading
+    // word was meant as a token, so claiming the operator got a TOKEN wrong
+    // would send them hunting for a typo they may not have made.
+    test('an unknown leading token is not answerable', () => {
+      askFor('r-peter');
+      expect(interpretInbound(db, context(PETER, 'ZZZZZZ value'))).toEqual({
+        action: 'rejected',
+        reason: 'unrecognised',
+      });
+    });
+  });
+
+  /**
+   * The two grammars share a table, so the same body must mean different
+   * things depending on what the token names. Asserting both readings side by
+   * side is the guard against one of them quietly swallowing the other again.
+   */
+  describe('the two grammars do not bleed into each other', () => {
+    test('`<token> resolve` answers a question and REFUSES an alert', () => {
+      const question = mintDelivery(db, {
+        kind: 'interview',
+        targetId: 'evt-1',
+        routeId: 'r-peter',
+        now: NOW,
+        ttlMs: TTL_MS,
+      });
+      const alert = mintFor('r-peter');
+
+      expect(interpretInbound(db, context(PETER, `${question.token} resolve`))).toMatchObject({
+        action: 'answer',
+        value: 'resolve',
+      });
+      expect(interpretInbound(db, context(PETER, `${alert.token} resolve`))).toEqual({
+        action: 'rejected',
+        reason: 'unrecognised',
+      });
+    });
+  });
 });
 
 /**