@celilo/cli 0.15.0 → 0.16.2

package/src/services/alerting/inbound.ts

@@ -12,20 +12,52 @@
  * A message from an address matching no route is discarded and logged WITHOUT
  * a reply. Replying would confirm the number is live and that this is a celilo
  * instance, which is free reconnaissance for anyone probing.
+ *
+ * ── ORDER MATTERS: RESOLVE THE TOKEN, THEN PICK THE GRAMMAR ────────────────
+ *
+ * The same table carries alert pages and deploy questions, and they want
+ * OPPOSITE parsing. An alert reply is a token and at most a verb; anything
+ * wordier is refused, because `<token> resolve` silently acknowledging an
+ * alert the operator meant to escalate is the worst outcome here. An interview
+ * answer is a token followed by arbitrary text, because the text IS the answer.
+ *
+ * Parsing before resolving cannot serve both, and #533 is what that cost: the
+ * alert grammar ran first, read every real answer as a sentence, and rejected
+ * it before the poller could ever see it was a question. The feature was dead
+ * for months and the operator was told `unrecognised`, which reads as their
+ * typing being wrong.
+ *
+ * A delivery knows its own kind, so the token is resolved FIRST and the
+ * grammar chosen from what it named. Which rule applies was never a property
+ * of the text.
  */
 
 import { eq } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { type NotificationDelivery, type Route, routes } from '../../db/schema';
-import { findLiveDelivery, normaliseToken } from './tokens';
+import { findLiveDeliveriesByPrefix, normaliseToken } from './tokens';
 
 /**
- * v1 grammar: a bare token acknowledges. `snooze` and `resolve` verbs are
- * deferred — ack is what an operator does at 3am, and every extra verb is
- * another thing to mistype under stress.
+ * v1 grammar: a token acknowledges. `snooze` and `resolve` verbs are deferred —
+ * ack is what an operator does at 3am, and every extra verb is another thing to
+ * mistype under stress.
  *
- * A bare `ack` with no token is accepted when the sender has exactly one
- * outstanding delivery, since the token adds nothing when there is no ambiguity.
+ * Deliberately forgiving about everything EXCEPT what the message means. An
+ * earlier cut accepted `<token> ack` but not `ack <token>`, so an operator who
+ * read "reply BPRJEH" and typed the natural "ack BPRJEH" was refused — the verb
+ * was parsed as the token, failed the length check, and the reply was rejected.
+ * That is a real page going unacknowledged over word order, so:
+ *
+ *   - the ack verb may come BEFORE the token, AFTER it, or not at all
+ *   - case never matters, for the verb or the token
+ *   - the token may be shortened to any unambiguous prefix (see below)
+ *
+ * `token` here is a CANDIDATE, not necessarily a whole token: resolution
+ * against what is actually outstanding happens in `interpretInbound`, because
+ * only the database knows which prefixes are unique right now.
+ *
+ * A bare ack with no token at all is accepted when the sender has exactly one
+ * outstanding delivery, since a token adds nothing when there is no ambiguity.
  */
 export type InboundIntent =
   | { kind: 'ack'; token: string }
@@ -33,37 +65,87 @@ export type InboundIntent =
   | { kind: 'unrecognised' };
 
 const ACK_VERB = /^(ack|ok|k|👍)$/iu;
-const TOKEN_SHAPE = /^[0-9ABCDEFGHJKMNPQRSTVWXYZ]{6}$/;
+/**
+ * One to six characters of the token alphabet. Not anchored to the full
+ * length: a prefix is legal input, and whether it identifies something is a
+ * question for the delivery table, not for a regex.
+ */
+const TOKEN_SHAPE = /^[0-9ABCDEFGHJKMNPQRSTVWXYZ]{1,6}$/;
 
 export function parseInbound(body: string): InboundIntent {
-  const trimmed = body.trim();
-  if (!trimmed) return { kind: 'unrecognised' };
+  const words = body.trim().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return { kind: 'unrecognised' };
+
+  // Strip ack synonyms wherever they appear. What remains must be the token,
+  // or nothing at all.
+  const remainder = words.filter((word) => !ACK_VERB.test(word));
+  if (remainder.length === 0) return { kind: 'bare_ack' };
+
+  // More than one non-verb word is not a token with politeness around it, it
+  // is a sentence — and a sentence may be a request celilo does not implement.
+  // Guessing at it risks acknowledging an alert the operator meant to escalate:
+  // an earlier cut let `<token> resolve` silently ACK, so the operator believed
+  // they had cleared an alert that was still firing. Doing nothing and saying
+  // so is strictly better than doing the wrong thing quietly.
+  if (remainder.length > 1) return { kind: 'unrecognised' };
+
+  const token = normaliseToken(remainder[0]);
+  if (!TOKEN_SHAPE.test(token)) return { kind: 'unrecognised' };
 
-  if (ACK_VERB.test(trimmed)) return { kind: 'bare_ack' };
+  return { kind: 'ack', token };
+}
 
-  const [first, ...rest] = trimmed.split(/\s+/);
-  const token = normaliseToken(first);
-  if (!TOKEN_SHAPE.test(token)) return { kind: 'unrecognised' };
+/** A message that leads with a token, and whatever text followed it. */
+export interface TokenLedMessage {
+  token: string;
+  /** Everything after the token, trimmed. Empty when the token stood alone. */
+  rest: string;
+}
 
-  // A verb after the token must be an ack synonym or nothing. An earlier cut
-  // ignored the verb entirely, which meant `<token> resolve` silently
-  // ACKNOWLEDGED — the operator believes they cleared the alert and it is
-  // still firing. Doing nothing and saying so is strictly better than doing
-  // the wrong thing quietly.
-  //
-  // `resolve` and `silence` are terminal operations, not reply verbs (design
-  // D10): every extra verb is another thing to mistype at 3am.
-  if (rest.length > 0 && !ACK_VERB.test(rest.join(' '))) {
-    return { kind: 'unrecognised' };
-  }
+/**
+ * Split a message that LEADS with a token, or null if it does not.
+ *
+ * This is the interview grammar and it is deliberately not the alert one: the
+ * page says `reply <TOKEN> <value>`, and the value is whatever follows,
+ * verbatim. It may contain spaces, punctuation, or a word that happens to look
+ * like a verb — second-guessing it would corrupt exactly the values an operator
+ * cannot easily retype.
+ *
+ * `parseInbound` cannot serve both. Its "more than one non-verb word is a
+ * sentence" rule is what protects an ALERT from `<token> resolve`, and it is
+ * also what made every real interview answer unrecognised (#533): a value is
+ * a sentence by construction. Which rule applies is not a property of the text
+ * — it is a property of what the token names, and only the delivery table
+ * knows that. So both readings are produced here and `interpretInbound`
+ * chooses between them AFTER resolving the token.
+ */
+export function parseTokenLed(body: string): TokenLedMessage | null {
+  const trimmed = body.trim();
+  if (!trimmed) return null;
 
-  return { kind: 'ack', token };
+  const boundary = trimmed.search(/\s/);
+  const head = boundary === -1 ? trimmed : trimmed.slice(0, boundary);
+  const token = normaliseToken(head);
+  if (!TOKEN_SHAPE.test(token)) return null;
+
+  return { token, rest: boundary === -1 ? '' : trimmed.slice(boundary).trim() };
 }
 
 export type InboundOutcome =
   | { action: 'ack'; delivery: NotificationDelivery; route: Route }
+  /** An answer to a deploy question. `value` is the operator's text, verbatim. */
+  | { action: 'answer'; delivery: NotificationDelivery; route: Route; value: string }
   | { action: 'ignored'; reason: 'unknown_sender' }
-  | { action: 'rejected'; reason: 'unknown_token' | 'wrong_sender' | 'ambiguous' | 'unrecognised' };
+  | {
+      action: 'rejected';
+      reason:
+        | 'unknown_token'
+        | 'wrong_sender'
+        | 'ambiguous'
+        | 'unrecognised'
+        /** A question was named, but no value was supplied to answer it with. */
+        | 'needs_value';
+    };
 
 function routeForAddress(db: DbClient, senderAddress: string): Route | undefined {
   return db.select().from(routes).where(eq(routes.address, senderAddress)).get();
@@ -91,10 +173,9 @@ export function interpretInbound(db: DbClient, context: InboundContext): Inbound
 
   const intent = parseInbound(context.body);
 
-  if (intent.kind === 'unrecognised') {
-    return { action: 'rejected', reason: 'unrecognised' };
-  }
-
+  // A bare ack names no token, so there is nothing to resolve and nothing a
+  // question could be answered with. It is an ALERT reply by construction —
+  // `outstandingForRoute` supplies alert deliveries only.
   if (intent.kind === 'bare_ack') {
     const outstanding = context.outstandingForRoute(route.id);
     if (outstanding.length === 0) return { action: 'rejected', reason: 'unknown_token' };
@@ -102,11 +183,59 @@ export function interpretInbound(db: DbClient, context: InboundContext): Inbound
     return { action: 'ack', delivery: outstanding[0], route };
   }
 
-  const delivery = findLiveDelivery(db, intent.token, context.now);
-  if (!delivery) return { action: 'rejected', reason: 'unknown_token' };
+  // Both readings of the text, neither yet privileged. The alert reading is
+  // the more constrained one, so it names the token when it applies; otherwise
+  // a leading token does.
+  const led = parseTokenLed(context.body);
+  const namesAToken = intent.kind === 'ack';
+  const candidate = namesAToken ? intent.token : led?.token;
+
+  // Nothing token-shaped anywhere: not a reply celilo can act on.
+  if (!candidate) return { action: 'rejected', reason: 'unrecognised' };
+
+  // A prefix is resolved against what is LIVE right now, so how much of the
+  // token an operator must type depends on what is actually outstanding — one
+  // alert, one character. Matching is deliberately global rather than scoped to
+  // this route: it keeps `wrong_sender` a distinguishable answer below, and a
+  // globally-unique prefix is a stricter bar than a per-route one.
+  const matches = findLiveDeliveriesByPrefix(db, candidate, context.now);
+  if (matches.length === 0) {
+    // Ordinary words are token-shaped surprisingly often — the alphabet is
+    // most of the Latin one, so `what is going on` leads with a perfectly
+    // well-formed `WHAT`. Only call it a token the operator got WRONG when the
+    // alert grammar agreed it was one; otherwise this is a sentence, and
+    // saying `unknown_token` would send them hunting for a typo they did not
+    // make.
+    return { action: 'rejected', reason: namesAToken ? 'unknown_token' : 'unrecognised' };
+  }
+
+  // Ambiguous is its own answer, never a guess. Taking the first match would
+  // acknowledge an alert the operator did not name.
+  if (matches.length > 1) return { action: 'rejected', reason: 'ambiguous' };
+
+  const delivery = matches[0];
 
   // Factor two: a valid token replayed from a different number is refused.
+  // Checked before the grammar so a stranger learns nothing about which of the
+  // two a token names.
   if (delivery.routeId !== route.id) return { action: 'rejected', reason: 'wrong_sender' };
 
+  // NOW the kind is known, so the right grammar can be applied to the body.
+  if (delivery.kind === 'interview') {
+    // The value must follow the token the question was asked with; a verb-led
+    // message (`ack <TOKEN>`) names no value and is not an answer.
+    if (!led || led.token !== candidate) return { action: 'rejected', reason: 'unrecognised' };
+    // Named the question but supplied nothing to answer it with. Distinct from
+    // `unrecognised`: the operator got the token right and stopped too soon,
+    // and telling them that is the difference between retyping six characters
+    // and giving up.
+    if (!led.rest) return { action: 'rejected', reason: 'needs_value' };
+    return { action: 'answer', delivery, route, value: led.rest };
+  }
+
+  // An alert. The strict grammar applies, which is what keeps `<token> resolve`
+  // from silently acknowledging something the operator meant to escalate.
+  if (intent.kind !== 'ack') return { action: 'rejected', reason: 'unrecognised' };
+
   return { action: 'ack', delivery, route };
 }

package/src/services/alerting/interview-responder.test.ts

@@ -4,7 +4,6 @@ import {
   decideInterviewDelivery,
   describeQuestion,
   isRefusedFamily,
-  parseInterviewAnswer,
 } from './interview-responder';
 
 const headless = { hasTty: false, hasBidirectionalRoute: true };
@@ -98,37 +97,6 @@ describe('composeInterviewBody', () => {
   });
 });
 
-describe('parseInterviewAnswer', () => {
-  test('takes everything after the token as the answer', () => {
-    expect(parseInterviewAnswer('K7QM2X www.example.com', 'K7QM2X')).toBe('www.example.com');
-  });
-
-  test('is case-insensitive on the token', () => {
-    expect(parseInterviewAnswer('k7qm2x www.example.com', 'K7QM2X')).toBe('www.example.com');
-  });
-
-  // An answer may legitimately contain spaces and punctuation. Second-guessing
-  // it would corrupt exactly the values that are painful to retype.
-  test('preserves an answer containing spaces and punctuation verbatim', () => {
-    expect(parseInterviewAnswer('K7QM2X my value: with, punctuation', 'K7QM2X')).toBe(
-      'my value: with, punctuation',
-    );
-  });
-
-  test('an answer that looks like a verb is still an answer', () => {
-    expect(parseInterviewAnswer('K7QM2X resolve', 'K7QM2X')).toBe('resolve');
-  });
-
-  test('a token with no value is not an answer', () => {
-    expect(parseInterviewAnswer('K7QM2X', 'K7QM2X')).toBeNull();
-    expect(parseInterviewAnswer('K7QM2X   ', 'K7QM2X')).toBeNull();
-  });
-
-  test('a different token does not match', () => {
-    expect(parseInterviewAnswer('ZZZZZZ value', 'K7QM2X')).toBeNull();
-  });
-});
-
 /**
  * The families disagree on payload shape, and reading the wrong field means an
  * operator gets the raw event type instead of the question.

package/src/services/alerting/interview-responder.ts

@@ -136,23 +136,12 @@ export function composeInterviewBody(input: {
   return lines.join('\n');
 }
 
-/**
- * Extract the answer from an inbound reply.
- *
- * Everything after the token is the value, verbatim and unparsed — an answer
- * may legitimately contain spaces, punctuation, or something that looks like a
- * verb, and second-guessing it would corrupt exactly the values an operator
- * cannot easily retype.
- */
-export function parseInterviewAnswer(body: string, token: string): string | null {
-  const trimmed = body.trim();
-  const upper = trimmed.toUpperCase();
-  const normalisedToken = token.toUpperCase();
-  if (!upper.startsWith(normalisedToken)) return null;
-
-  const answer = trimmed.slice(token.length).trim();
-  return answer.length > 0 ? answer : null;
-}
+// `parseInterviewAnswer` lived here and is gone. It was correct and had the
+// tests to prove it, and it was never reachable: the caller only ran it for a
+// body the ALERT grammar had already accepted, which no real answer ever was
+// (#533). Extraction now happens in `interpretInbound` — the one place that
+// knows a delivery's kind before it parses — so the reply grammar exists once
+// rather than in two halves that could disagree.
 
 /** Severity an interview question is delivered at — never a page-worthy one. */
 export const INTERVIEW_SEVERITY: AlertSeverity = 'warning';

package/src/services/alerting/tokens.ts

@@ -13,7 +13,7 @@
  */
 
 import { randomInt, randomUUID } from 'node:crypto';
-import { and, eq, gt, isNull } from 'drizzle-orm';
+import { and, eq, gt, isNull, like } from 'drizzle-orm';
 import type { DbClient } from '../../db/client';
 import { type NotificationDelivery, notificationDeliveries } from '../../db/schema';
 
@@ -100,6 +100,44 @@ export function findLiveDelivery(
     .get();
 }
 
+/**
+ * Every live delivery whose token STARTS WITH `prefix`.
+ *
+ * An operator typing at 3am should not have to copy six characters exactly.
+ * They need only enough to be unambiguous, and "unambiguous" is scoped to what
+ * is actually outstanding right now — consumed and expired deliveries are not
+ * candidates, so yesterday's tokens cannot make today's prefix ambiguous.
+ *
+ * Returning every match rather than the first is the point: the caller must be
+ * able to tell "no such token" from "you were ambiguous, be more specific".
+ * Silently taking the first match would acknowledge an alert the operator did
+ * not mean, which is worse than asking again.
+ *
+ * The shortening does not weaken authentication in the way it first appears.
+ * The token was never a secret on its own — the sender address is the other
+ * factor and is unaffected — and the search space here is not 32^6 but the
+ * handful of alerts live at this moment.
+ */
+export function findLiveDeliveriesByPrefix(
+  db: DbClient,
+  prefix: string,
+  now: Date,
+): NotificationDelivery[] {
+  const normalised = normaliseToken(prefix);
+  if (!normalised) return [];
+  return db
+    .select()
+    .from(notificationDeliveries)
+    .where(
+      and(
+        like(notificationDeliveries.token, `${normalised}%`),
+        isNull(notificationDeliveries.consumedAt),
+        gt(notificationDeliveries.expiresAt, now),
+      ),
+    )
+    .all();
+}
+
 export function consumeDelivery(db: DbClient, deliveryId: string, now: Date): void {
   db.update(notificationDeliveries)
     .set({ consumedAt: now })