@pithy-sh/testers 0.1.0

package/src/error/errors.ts

@@ -0,0 +1,229 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * The `testers/*` throw vehicles.
+ *
+ * **An opt-in link, a tester's email address, and a cohort's roster belong in `detail`, never
+ * `message`.** The HTTP codec strips `detail`, and that is the single security boundary — a public
+ * opt-in route answers unauthenticated strangers, so anything it says is said to everyone. Every
+ * default `message` below is written to be safe to hand a stranger, and every one of them is
+ * deliberately incurious: `TestersInvalidTokenError` covers a malformed link, an expired one, a forged
+ * signature, and a link naming a deleted cohort with the same words, so a caller holding a guess cannot
+ * use the response to narrow it down.
+ */
+
+/** The variable parts every testers error accepts; the `code` and `status` are fixed by the subclass. */
+interface TestersErrorArgs {
+  message?: string;
+  action?: string;
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`.
+   */
+  params?: MessageParams;
+}
+
+/** No cohort answers to that id. */
+export class TestersCohortNotFoundError extends PithyError {
+  constructor(args: TestersErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "testers/cohort_not_found",
+        status: 404,
+        message: args.message ?? "No such cohort.",
+        action: args.action ?? "List your cohorts with `pithy testers list` and retry with an id from there.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** No member of that cohort answers to that id or address. */
+export class TestersMemberNotFoundError extends PithyError {
+  constructor(args: TestersErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "testers/member_not_found",
+        status: 404,
+        message: args.message ?? "No such tester on that cohort.",
+        action: args.action ?? "Check the roster with `pithy testers roster <cohort>`.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * The opt-in link failed verification, for any reason at all.
+ *
+ * One error for every failing step is the point. A stranger who guesses at a link should learn only
+ * that it did not work — not whether the signature was wrong, whether it had expired, or whether the
+ * cohort it named exists. `detail` carries the step for the log.
+ */
+export class TestersInvalidTokenError extends PithyError {
+  constructor(args: TestersErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "testers/invalid_token",
+        status: 400,
+        message: args.message ?? "That confirmation link is no longer valid.",
+        action: args.action ?? "Ask the developer who invited you to send a fresh invitation.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** The cohort is at its roster cap. */
+export class TestersRosterFullError extends PithyError {
+  constructor(args: TestersErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "testers/roster_full",
+        status: 409,
+        message: args.message ?? "That cohort's roster is full.",
+        action: args.action ?? "Remove a lapsed tester, or raise the cohort's maximum roster size.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** That address is already on the roster in a live state. */
+export class TestersAlreadyOnRosterError extends PithyError {
+  constructor(args: TestersErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "testers/already_on_roster",
+        status: 409,
+        message: args.message ?? "That tester is already on this cohort.",
+        action: args.action ?? "Use resend to send them another invitation without losing their history.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** Every selected tester is inside the per-tester nudge cooldown, so nothing was sent. */
+export class TestersNudgeCooldownError extends PithyError {
+  constructor(args: TestersErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "testers/nudge_cooldown",
+        status: 429,
+        message: args.message ?? "Every one of those testers was nudged too recently.",
+        action: args.action ?? "Wait for the cooldown to pass, or select testers who have not been nudged.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * The address withdrew from this cohort itself, so it may not be invited back onto it.
+ *
+ * `lapsed` has exactly one producer: the tester's own `POST /opt-out/:token`. It is therefore never a
+ * roster state a developer chose — it is a person's decision, and the page they saw when they made it
+ * says "you will not hear from this test again". Reviving them restored the row to `invited` with a
+ * fresh token and a zeroed nudge count, and `POST /invite` sends by default, so one call re-mailed
+ * somebody who had asked to be left alone and restarted the whole chase sequence against them.
+ *
+ * Every other send path already refused a lapsed member — `resend`, `nudge`, and the daily pass all
+ * check. `invite` was the one that did not, and it is the path a routine contact-list re-import takes.
+ *
+ * `removed` stays revivable, deliberately: that is the developer's own act on their own roster, and
+ * undoing it takes nobody's consent away.
+ */
+export class TestersWithdrawnError extends PithyError {
+  constructor(args: TestersErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "testers/withdrawn",
+        status: 409,
+        message: args.message ?? "That tester asked to be taken off this test.",
+        action:
+          args.action ??
+          "Their decision stands. Invite somebody else, or ask them directly and start a new cohort if they agree.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * The cohort is closed, so this operation would write to or send from a finished program.
+ *
+ * `closedAt` was stamped by `closeCohort` and then read by exactly one filter, so everything that did
+ * not go through that filter carried on: the control-plane routes still invited, resent and nudged, and
+ * `pithy testers run --cohort <closed>` still mailed and still wrote a snapshot. Both the CLI and the
+ * schema's own description promise "nothing further is sent", and a promise enforced in one place is a
+ * promise for one path.
+ */
+export class TestersCohortClosedError extends PithyError {
+  constructor(args: TestersErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "testers/cohort_closed",
+        status: 409,
+        message: args.message ?? "That cohort is closed.",
+        action: args.action ?? "Create a new cohort. A closed one keeps its history but sends nothing further.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** The caller supplied nudge copy, but this deployment pins the shipped defaults. */
+export class TestersCopyNotAllowedError extends PithyError {
+  constructor(args: TestersErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "testers/copy_not_allowed",
+        status: 403,
+        message: args.message ?? "This deployment does not accept supplied nudge copy.",
+        action: args.action ?? "Send the nudge without a subject or body, or enable nudges.allowCopyOverride.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/** The capability is composed but cannot complete this operation without more wiring. */
+export class TestersNotConfiguredError extends PithyError {
+  constructor(args: TestersErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "testers/not_configured",
+        status: 500,
+        message: args.message ?? "The testers capability is not fully configured.",
+        action: args.action ?? "Complete the testers block in pithy.config.ts and redeploy.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}

package/src/health/score.ts

@@ -0,0 +1,225 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { HealthCredits, HealthPenalties, SurvivalPriors, TesterPlatform } from "../config/config";
+import type { Observability, RiskBand } from "../data/enums";
+
+/**
+ * Per-tester health: how worried to be about one person, and why.
+ *
+ * **Health is a risk signal, never a membership signal.** A tester who opted in and never opens the app
+ * still counts toward Google's twelve — Google counts opt-ins, not engagement — so nothing in this file
+ * may remove anybody from the count. What it produces is the only early-warning signal that exists: a
+ * tester dark for eight days is the one most likely to have quietly opted out or uninstalled, and
+ * knowing that on day eight is worth a great deal more than discovering it on day fourteen.
+ *
+ * **Every term is reported individually.** A score is returned with the list of factors that produced
+ * it, so a developer can see that 45 of their missing points came from `dark_8_10` rather than being
+ * asked to accept a number. An unauditable score is an unaccountable one, and this whole capability is
+ * arguing that the developer should not have to take anyone's word for a figure.
+ *
+ * **The formula is additive and integer, on purpose.** A logistic curve would fit the data better if
+ * there were data to fit; there is not, these are declared priors, and a curve would only make the
+ * arbitrariness harder to see. Addition can be explained in one sentence per line.
+ */
+
+/** The best score a tester can hold. */
+const MAX_HEALTH = 100;
+
+/** One term of a health score, with the sentence that justifies it. */
+export interface HealthFactor {
+  /** A stable identifier for this term, e.g. `dark_8_10`. Safe to key a UI off. */
+  readonly code: string;
+  /** The signed contribution to the score. Penalties are negative, credits positive. */
+  readonly points: number;
+  /** One sentence explaining this factor to a developer. */
+  readonly reason: string;
+}
+
+/** What scoring one tester needs to know about them. Everything here is observed, not estimated. */
+export interface HealthInput {
+  /** How much of this tester we can see at all. Decides whether they get a score or a stated absence of one. */
+  readonly observability: Observability;
+  /**
+   * Days since the last sign of life — a session refresh, a device sighting, or their own opt-in,
+   * whichever is most recent. Null when they were never linked to a user at all.
+   */
+  readonly daysDark: number | null;
+  /** Sessions inside the cohort's window. */
+  readonly sessionsInWindow: number;
+  /** How many devices are registered to them. */
+  readonly deviceCount: number;
+  /** Whether at least one of those devices runs the cohort's target platform. */
+  readonly hasTargetPlatformDevice: boolean;
+  /** Whether they have authenticated at all since following the opt-in link. */
+  readonly sessionSinceOptIn: boolean;
+  /** Nudges sent with no subsequent sign of life. Each is an unanswered probe. */
+  /** Nudges enqueued since they last answered one — cleared by accepting or confirming, not by activity. */
+  readonly unansweredNudges: number;
+  /** Days since they followed the opt-in link, or null if they have not. */
+  readonly daysSinceOptIn: number | null;
+  /** The cohort's target platform, or null to disable the device term entirely. */
+  readonly targetPlatform: TesterPlatform | null;
+}
+
+/** A scored tester: the number, the band it falls in, and every term that produced it. */
+export interface HealthResult {
+  /** 0–100, or null for a tester we cannot observe. Null is not zero — absence of evidence is not evidence of risk. */
+  readonly health: number | null;
+  /** Why the score is null when it is null. A UI must render `unobservable` gray, never red. */
+  readonly basis: "scored" | "unobservable" | "unreachable";
+  /** The band the score falls in, which selects the survival prior. */
+  readonly riskBand: RiskBand;
+  /** Every term, so the number can be audited line by line. Empty for an unscored tester. */
+  readonly factors: readonly HealthFactor[];
+}
+
+/** The dark-day bands. Exclusive: exactly one fires, and the widest matching one wins. */
+const DARK_BANDS: readonly { min: number; max: number; code: string; key: keyof HealthPenalties; reason: string }[] = [
+  {
+    min: 3,
+    max: 4,
+    code: "dark_3_4",
+    key: "darkThreeToFour",
+    reason: "Three days quiet is noise rather than signal — worth a nudge, not an alarm.",
+  },
+  {
+    min: 5,
+    max: 7,
+    code: "dark_5_7",
+    key: "darkFiveToSeven",
+    reason: "A week without opening the app is the first real sign of drift.",
+  },
+  {
+    min: 8,
+    max: 10,
+    code: "dark_8_10",
+    key: "darkEightToTen",
+    reason: "Eight days dark is the strongest single predictor of a silent uninstall.",
+  },
+  {
+    min: 11,
+    max: 13,
+    code: "dark_11_13",
+    key: "darkElevenToThirteen",
+    reason: "Nearly the whole window with no sign of life.",
+  },
+  {
+    min: 14,
+    max: Number.POSITIVE_INFINITY,
+    code: "dark_14_plus",
+    key: "darkFourteenPlus",
+    reason: "Gone for longer than the test you are asking them to complete.",
+  },
+];
+
+/** The band a score falls in. Bands are inclusive at their lower bound. */
+export function bandFor(health: number | null): RiskBand {
+  if (health === null) return "unknown";
+  if (health >= 80) return "healthy";
+  if (health >= 60) return "watch";
+  if (health >= 30) return "at_risk";
+  return "critical";
+}
+
+/** The published daily-survival prior for a band. */
+export function survivalFor(band: RiskBand, observability: Observability, priors: SurvivalPriors): number {
+  if (observability === "unreachable") return priors.unreachable;
+  switch (band) {
+    case "healthy":
+      return priors.healthy;
+    case "watch":
+      return priors.watch;
+    case "at_risk":
+      return priors.atRisk;
+    case "critical":
+      return priors.critical;
+    default:
+      return priors.unknown;
+  }
+}
+
+/**
+ * Score one tester.
+ *
+ * An unobservable or unreachable tester returns `health: null` with a stated basis rather than a low
+ * number. This is the single most important decision in the file: if an adopter's test flow never asks
+ * anyone to sign in, *every* tester is unobservable, and scoring them badly would paint a perfectly
+ * healthy cohort red and drive a fortnight of pointless nudging. Null makes the blindness visible in
+ * the aggregate — as `observedCoverage` and a widening confidence band — instead of hiding it inside a
+ * number that looks like knowledge.
+ */
+export function scoreHealth(input: HealthInput, penalties: HealthPenalties, credits: HealthCredits): HealthResult {
+  if (input.observability === "unreachable") {
+    return { health: null, basis: "unreachable", riskBand: "unknown", factors: [] };
+  }
+  if (input.observability === "unobservable" || input.daysDark === null) {
+    return { health: null, basis: "unobservable", riskBand: "unknown", factors: [] };
+  }
+
+  const factors: HealthFactor[] = [];
+
+  const band = DARK_BANDS.find(
+    (entry) => input.daysDark !== null && input.daysDark >= entry.min && input.daysDark <= entry.max,
+  );
+  if (band) {
+    factors.push({ code: band.code, points: -penalties[band.key], reason: band.reason });
+  }
+
+  // Gated on the cohort declaring a target platform. An `ios` cohort penalizing a missing Android
+  // device, or a cohort with no platform at all penalizing everybody, would both be noise.
+  if (input.targetPlatform !== null && !input.hasTargetPlatformDevice) {
+    factors.push({
+      code: "no_target_platform_device",
+      points: -penalties.noTargetPlatformDevice,
+      reason: `The test targets ${input.targetPlatform}, and no ${input.targetPlatform} device is registered for them.`,
+    });
+  }
+
+  if (input.unansweredNudges > 0) {
+    const raw = input.unansweredNudges * penalties.unansweredNudge;
+    factors.push({
+      code: "unanswered_nudges",
+      points: -Math.min(raw, penalties.unansweredNudgeCap),
+      reason: "Each nudge is a probe. Several unanswered probes are themselves an answer.",
+    });
+  }
+
+  if (input.daysSinceOptIn !== null && !input.sessionSinceOptIn) {
+    factors.push({
+      code: "session_never_since_optin",
+      points: -penalties.noSessionSinceOptIn,
+      reason: "They confirmed the opt-in link but have not opened the app since.",
+    });
+  }
+
+  if (input.sessionsInWindow >= credits.engagedSessionThreshold) {
+    factors.push({
+      code: "engaged",
+      points: credits.engaged,
+      reason: `${credits.engagedSessionThreshold} or more sessions in the window is a tester who is actually testing.`,
+    });
+  }
+
+  if (input.deviceCount >= 2) {
+    factors.push({
+      code: "multi_device",
+      points: credits.multiDevice,
+      reason: "Two registered devices is someone invested enough to install twice.",
+    });
+  }
+
+  // Without this, a tester who confirmed three hours ago reads as neglected on arrival: they have no
+  // sessions yet, so every engagement term is against them and none is for them.
+  if (input.daysSinceOptIn !== null && input.daysSinceOptIn <= credits.freshOptInDays) {
+    factors.push({
+      code: "fresh_optin",
+      points: credits.freshOptIn,
+      reason: "Opted in within the last few days, so there has been no time to decay.",
+    });
+  }
+
+  const total = factors.reduce((sum, factor) => sum + factor.points, MAX_HEALTH);
+  const health = Math.min(MAX_HEALTH, Math.max(0, total));
+  return { health, basis: "scored", riskBand: bandFor(health), factors };
+}

package/src/http/guards.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import type { MiddlewareHandler } from "hono";
+
+/**
+ * Route guards.
+ *
+ * **The scope constants moved to `./scopes`** (#315). A management client reads them to render what a
+ * connection may do, and it reads them in a browser — so they cannot live in a module that imports
+ * Hono middleware and `PithyHonoEnv`. The gates stayed here; the names they demand are next door, and
+ * the routes import both.
+ *
+ * `requireAuth` is **copied** rather than imported from `@pithy-sh/auth`, matching every other
+ * capability in the repo. Importing a gate from another package would make that package a hard
+ * dependency, and a package that borrows its authorization fails *open* when the lender is absent. With
+ * the guard local, a project that never installed auth leaves `c.var.auth` null and every guarded route
+ * denies — which is the only acceptable direction for that failure to go.
+ */
+
+/**
+ * Require an authenticated caller. Rejects a request whose `AuthContext` was never filled, which means
+ * either no credential or an invalid one.
+ */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}

package/src/http/pages.ts

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * The three HTML pages a tester sees.
+ *
+ * Separate from `routes.ts` because they are pure — a string in, a `Response` out, no database and no
+ * config — and because that is what makes their contents assertable. The opt-out page in particular is
+ * a security surface: it exists so that withdrawing takes a form submission rather than a link
+ * following, and a test that proves it renders a form is worth more than a comment saying it should.
+ *
+ * Distinct from `view.ts`, which shapes the JSON a dashboard receives. Same layer, different audience.
+ */
+
+/**
+ * Escape a value before it goes into the HTML these routes render.
+ *
+ * The store URL is developer-supplied and already host-allowlisted, so this is defense in depth rather
+ * than the only guard — but it is a URL interpolated into an `href` on a page shown to a stranger, and
+ * "already validated elsewhere" is how injection survives a refactor.
+ */
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+export function page(title: string, body: string): Response {
+  return new Response(
+    `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${title}</title></head><body style="font-family:system-ui,-apple-system,sans-serif;max-width:34rem;margin:15vh auto;padding:0 1.5rem;line-height:1.55"><h1 style="font-size:1.4rem;font-weight:600;margin:0 0 .75rem">${title}</h1><p style="margin:0;color:#555">${body}</p></body></html>`,
+    { status: 200, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } },
+  );
+}
+
+/**
+ * The page that hands a tester the store's own opt-in link.
+ *
+ * The two lines of guidance are not padding. Opening the link in the store app rather than a browser,
+ * and signing in with a different account than the one invited, are the two failures that produce
+ * `App not available` — the single most common way a closed test goes wrong for a tester who did
+ * everything they were asked.
+ */
+export function storePage(url: string, platform: "android" | "ios"): Response {
+  const store = platform === "ios" ? "TestFlight" : "Google Play";
+  const safeUrl = escapeHtml(url);
+  return new Response(
+    `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Join the test</title></head><body style="font-family:system-ui,-apple-system,sans-serif;max-width:34rem;margin:12vh auto;padding:0 1.5rem;line-height:1.55"><h1 style="font-size:1.4rem;font-weight:600;margin:0 0 .75rem">One more step.</h1><p style="margin:0 0 1.5rem;color:#555">Open ${escapeHtml(store)} to join the test and install the app.</p><p style="margin:0 0 1.75rem"><a href="${safeUrl}" style="display:inline-block;background:#111;color:#fff;text-decoration:none;padding:13px 26px;border-radius:8px;font-weight:600">Join on ${escapeHtml(store)}</a></p><p style="margin:0 0 .5rem;color:#555;font-size:.925rem">Two things worth knowing, because they are what usually goes wrong:</p><ul style="margin:0 0 1.5rem;padding-left:1.15rem;color:#555;font-size:.925rem"><li style="margin-bottom:.4rem">Open it in a browser, not inside the ${escapeHtml(store)} app.</li><li>Sign in with the same address this email reached you at. A different account cannot join.</li></ul><p style="margin:0;color:#888;font-size:.85rem;word-break:break-all">If the button does not work: ${safeUrl}</p></body></html>`,
+    { status: 200, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } },
+  );
+}
+
+/**
+ * The page that asks a tester to confirm they meant to withdraw.
+ *
+ * A form rather than a link, because the whole point is that following it requires an actor who
+ * submits forms. A mail client prefetching the URL renders this and changes nothing.
+ */
+export function confirmOptOutPage(action: string): Response {
+  return new Response(
+    `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Leave the test?</title></head><body style="font-family:system-ui,-apple-system,sans-serif;max-width:34rem;margin:15vh auto;padding:0 1.5rem;line-height:1.55"><h1 style="font-size:1.4rem;font-weight:600;margin:0 0 .75rem">Leave the test?</h1><p style="margin:0 0 1.5rem;color:#555">You will not be contacted about it again. If you meant to do this, confirm below.</p><form method="post" action="${escapeHtml(action)}"><button type="submit" style="background:#111;color:#fff;border:0;padding:13px 26px;border-radius:8px;font-weight:600;font-size:1rem;cursor:pointer">Yes, take me off</button></form><p style="margin:1.5rem 0 0;color:#888;font-size:.85rem">Close this page to stay on the test.</p></body></html>`,
+    { status: 200, headers: { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" } },
+  );
+}