@pithy-sh/support 0.1.0

package/src/mime/threading.ts

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * RFC 5322 threading — turning `Message-ID`, `In-Reply-To`, and `References` into a conversation.
+ *
+ * **Threading is done on ids, never on the subject.** Subject matching is what makes two unrelated
+ * people who both wrote "Refund" land in one thread, and it is what splits a real conversation the
+ * moment somebody's client localizes `Re:` to `Aw:` or `Antw:`. The headers exist precisely so this
+ * does not have to be guessed, and every mail client sets them.
+ *
+ * The chain is tried in the order that goes from most precise to least: `In-Reply-To` names exactly
+ * one message, so it is asked first; `References` is the whole ancestry, so it is the fallback for a
+ * client that dropped `In-Reply-To` or a reply to a message that reached us out of order. Reading
+ * `References` **newest-first** matters — the last entry is the nearest ancestor, and starting at the
+ * root would attach a reply to the top of a long thread rather than to the message it answers.
+ */
+
+/** The longest `References` chain kept. Bounded because the header is attacker-controlled and unbounded by spec. */
+export const MAX_REFERENCES = 50;
+
+/** The longest single message id kept, after unwrapping. Anything longer is not an id a client produced. */
+const MAX_ID_LENGTH = 512;
+
+/**
+ * Strip the angle brackets from a message id and bound it.
+ *
+ * Stored without brackets so a lookup is plain equality: the brackets are transport syntax, and one
+ * path storing `<a@b>` while another queries `a@b` is a threading bug that only shows up on replies.
+ */
+export function normalizeMessageId(value: string | null | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim().replace(/^<+/, "").replace(/>+$/, "").trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_ID_LENGTH) return undefined;
+  // Whitespace inside means this was a list, not an id — the caller wanted `parseReferences`.
+  return /\s/.test(trimmed) ? undefined : trimmed;
+}
+
+/**
+ * Parse a `References` (or `In-Reply-To`) header into ids, oldest first, deduplicated and bounded.
+ *
+ * `postal-mime` hands `references` back as the raw header string, so the splitting is ours. Angle
+ * brackets are the delimiter when they are present and whitespace is the fallback when they are not,
+ * because a malformed header from a hand-rolled sender is a normal input here.
+ *
+ * **When the chain is over the cap, the OLDEST entries are dropped, not the newest.** That direction
+ * is the whole point: `parentCandidates` reads this list from the newest end backwards, because the
+ * nearest ancestor is the message a reply actually answers. Capping from the other end would discard
+ * exactly the ids the lookup wants first and keep the ones it would reach last — so a long thread
+ * would silently stop threading on `References` and fall back to whatever `In-Reply-To` happened to
+ * survive. Same rule `buildReferencesHeader` follows on the way out, and RFC 5322 §3.6.4 says to trim
+ * this end for the same reason.
+ */
+export function parseReferences(value: string | null | undefined): string[] {
+  if (typeof value !== "string") return [];
+  const bracketed = [...value.matchAll(/<([^<>]+)>/g)].map((match) => match[1] ?? "");
+  const candidates = bracketed.length > 0 ? bracketed : value.split(/\s+/);
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    const id = normalizeMessageId(candidate);
+    if (id) seen.add(id);
+  }
+  const ids = [...seen];
+  return ids.length > MAX_REFERENCES ? ids.slice(ids.length - MAX_REFERENCES) : ids;
+}
+
+/**
+ * The ids to look a parent up by, most precise first.
+ *
+ * The order is the whole content of this function: `In-Reply-To`, then `References` from the newest
+ * entry backwards. A caller resolves the first one it recognizes and stops.
+ */
+export function parentCandidates(inReplyTo: string | undefined, references: readonly string[]): string[] {
+  const ordered = [...(inReplyTo ? [inReplyTo] : []), ...[...references].reverse()];
+  return [...new Set(ordered)];
+}
+
+/**
+ * Build the `References` header value for an outgoing reply.
+ *
+ * RFC 5322 §3.6.4: a reply's `References` is the parent's `References` followed by the parent's
+ * `Message-ID`. Getting this wrong is not cosmetic — it is the difference between the customer
+ * seeing one conversation and seeing a new mail every time somebody answers them, which is the
+ * single most visible way a support inbox looks broken from the outside. It is also the reason
+ * replying belongs in the Worker rather than in a dashboard: only the Worker holds the chain.
+ *
+ * The result is bracketed and space-separated, ready to be a header value, and bounded from the
+ * *front* — RFC 5322 says to drop the oldest entries when a chain has to be trimmed, because the
+ * recent ones are what a client threads on.
+ */
+export function buildReferencesHeader(parentReferences: readonly string[], parentMessageId?: string): string {
+  // The parent's id is removed from the inherited chain before being re-appended, so it lands *last*
+  // even when it already appeared mid-chain. A plain `Set` would keep its first position instead, and
+  // §3.6.4's "parent's id last" property would quietly not hold for the one input where it is easiest
+  // to get wrong: a reply to a message that was itself already referenced.
+  const inherited = parentReferences.filter((id) => id !== parentMessageId);
+  const chain = [...inherited, ...(parentMessageId ? [parentMessageId] : [])];
+  const deduped = [...new Set(chain)];
+  const trimmed = deduped.length > MAX_REFERENCES ? deduped.slice(deduped.length - MAX_REFERENCES) : deduped;
+  return trimmed.map((id) => `<${id}>`).join(" ");
+}
+
+/**
+ * Mint a `Message-ID` for an outgoing reply.
+ *
+ * Ours to generate, because a message we send has to be nameable by the customer's own reply — their
+ * client will put this value in its `In-Reply-To`, and that is how the answer comes back to the same
+ * thread. The domain half is taken from the address it is sent as, so the id is plausible to a
+ * receiving spam filter rather than pointing at a domain we do not control.
+ */
+export function mintMessageId(fromAddress: string, uuid: string): string {
+  const domain = fromAddress.slice(fromAddress.lastIndexOf("@") + 1) || "localhost";
+  return `${uuid}@${domain}`;
+}
+
+/**
+ * The subject line for a reply — `Re: ` prefixed exactly once.
+ *
+ * Match `Re:` case-insensitively and allow the bracketed count some clients add (`Re[2]:`), so
+ * answering a long thread does not build `Re: Re: Re: Re:`. Non-English prefixes are deliberately
+ * left alone: they are unbounded in practice, and a stray `Aw: Re:` is cosmetic, while stripping a
+ * word that happened to look like a prefix would change what the customer wrote.
+ */
+export function replySubject(subject: string): string {
+  const trimmed = subject.trim();
+  return /^re(\[\d+\])?:/i.test(trimmed) ? trimmed : `Re: ${trimmed}`;
+}

package/src/mime/truncate.ts

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Truncation that counts **bytes**, because the limits it serves are byte limits.
+ *
+ * `String.prototype.slice` counts UTF-16 code units, so a bound written as "256 KB" admits 256 K
+ * *characters* — three times that in bytes for CJK, four for most emoji. The bounds in this package
+ * exist to keep a row under D1's 2,000,000-byte ceiling, and a character-counted bound does not do
+ * that: a large CJK message sails through every check and then fails the insert, at which point the
+ * inbound handler swallows the error and the customer's mail is gone. Counting the thing the limit is
+ * about is the whole fix.
+ *
+ * Truncation lands on a code-point boundary, so the result is never a lone surrogate — which would be
+ * invalid text in the database and could break a JSON encode downstream.
+ */
+
+const encoder = new TextEncoder();
+
+/** How many bytes this string occupies as UTF-8. */
+export function byteLength(value: string): number {
+  return encoder.encode(value).byteLength;
+}
+
+/**
+ * `value`, cut to at most `maxBytes` UTF-8 bytes, never mid-code-point.
+ *
+ * **Binary search, because the obvious loop is quadratic.** Walking down one code unit at a time and
+ * re-encoding the prefix each step is O(n) encodes of O(n) bytes, and the starting point makes it
+ * worse: `maxBytes` *code units* can be four times `maxBytes` *bytes*, so multi-byte text starts far
+ * above the answer and decrements toward it. Measured on the real constants, a 400k-character CJK
+ * body took 174,763 iterations and about three minutes of CPU — inside an `email()` handler, which
+ * the runtime kills long before that, so the message was never stored and every redelivery hit the
+ * same wall. A size bound that loses the message is worse than no bound.
+ *
+ * The search runs over `[0, min(length, maxBytes)]`: `maxBytes` code units is an upper bound because
+ * every code unit is at least one byte, and the predicate is monotone, so O(log n) encodes settle it.
+ */ export function truncateToBytes(value: string, maxBytes: number): string {
+  // The common case by far, and it costs one encode rather than a search.
+  if (maxBytes <= 0) return "";
+  if (byteLength(value) <= maxBytes) return value;
+
+  // Largest code-unit count whose UTF-8 encoding still fits. Monotone in `end`, so bisect it.
+  let low = 0;
+  let high = Math.min(value.length, maxBytes);
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (byteLength(value.slice(0, mid)) <= maxBytes) low = mid;
+    else high = mid - 1;
+  }
+
+  // `slice` on a code-unit index can split a surrogate pair; stepping back one unit repairs it.
+  const cut = value.slice(0, low);
+  return /[\uD800-\uDBFF]$/.test(cut) ? cut.slice(0, -1) : cut;
+}

package/src/provision/provisionSupport.ts

@@ -0,0 +1,179 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import { GLOBAL_SCOPE } from "@pithy-sh/core/src/naming/environment";
+import { resourceName } from "@pithy-sh/core/src/naming/resource";
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import { type ManagedEnvironment, managedEnvironments } from "@pithy-sh/secrets/src/scope";
+import { SUPPORT_CAPABILITY } from "../workflows/specs";
+
+/**
+ * The provisioning orchestration for the support capability — the live counterpart to
+ * `pithy add support`'s config wiring.
+ *
+ * Three things have to exist before a support inbox works, and none of them can be a binding an
+ * adopter hand-writes: the R2 bucket attachments and raw messages land in, the prebuilt classification
+ * worker per environment, and — the one that actually delivers the mail — an Email Routing rule
+ * pointing the support address at the app worker.
+ *
+ * The live Cloudflare/wrangler steps sit behind the {@link SupportProvisioner} seam, so the
+ * orchestration (order, idempotency, per-env fan-out) is unit-tested without touching Cloudflare.
+ * Every step is idempotent; re-running is a no-op.
+ *
+ * ## The routing rule is opt-in, and that is a safety decision
+ *
+ * `ensureRoutingRule` returns `skipped: true` when no routing config is supplied, exactly as
+ * `@pithy-sh/email`'s does — because **enabling Email Routing on a zone points its MX at Cloudflare.**
+ * Creating a rule on the wrong zone would move an adopter's real inbound mail off their existing
+ * provider, which is not a mistake a provisioning command gets to make on their behalf. So the zone,
+ * the address, and the target worker are all explicit flags, and a project that has not decided yet
+ * provisions everything else and adds the rule later.
+ *
+ * The rule name is `<project>-global-support-inbound`, deliberately distinct from `@pithy-sh/email`'s
+ * `<project>-global-email-bounce`. Idempotency in `ensureWorkerRoute` keys on the rule *name*, so
+ * sharing one would make whichever capability provisioned second silently believe its rule already
+ * existed — and the project segment is what stops two Pithy projects on one zone doing the same to
+ * each other, with the loser's customer mail delivered to the winner's Worker.
+ */
+
+/**
+ * The name of the Email Routing rule this capability creates, for one project. Distinct from the
+ * bounce handler's, and `global` in the environment slot because there is one rule per zone: the
+ * environments are separated by which app Worker the rule is pointed at, not by the rule.
+ *
+ * **Still on the generic composer**, and deliberately: an Email Routing rule is not a namespace
+ * `@pithy-sh/core/src/naming/limits` carries a verified Cloudflare cap for, and the facade exists so a
+ * kind of thing brings its own number rather than borrowing one. It takes the conservative default
+ * until that namespace lands — the same call `@pithy-sh/email`'s bounce rule makes.
+ */
+export function supportRoutingRuleName(project: string): string {
+  return resourceName({ project, env: GLOBAL_SCOPE, thing: `${SUPPORT_CAPABILITY}-inbound` });
+}
+
+/**
+ * The deployed Worker name for a project's environment — also its resolved config basename. Composed
+ * through core's naming facade under the **`worker`** namespace, so it is measured against a Worker
+ * script's 63 and the environment is validated on the way through. One source, so the name the CLI
+ * audits and deletes under cannot drift from the name it deploys under.
+ */
+export function supportWorkerName(project: string, env: ManagedEnvironment): string {
+  return resourceNames(project).env(env).worker(SUPPORT_CAPABILITY);
+}
+
+/** The live Cloudflare/wrangler seam. Each step must be idempotent. */
+export interface SupportProvisioner {
+  /**
+   * Verify account prerequisites before any resource is created — most importantly a registered
+   * `workers.dev` subdomain, which Cloudflare requires to deploy the Workflow-hosting worker.
+   */
+  preflight(): Promise<void>;
+  /**
+   * Create (or reuse) the R2 bucket attachments and raw messages live in. Idempotent.
+   *
+   * Returns `skipped: true` when the capability is configured with attachments off — a bucket nobody
+   * writes to is a resource an adopter did not ask for.
+   */
+  ensureBucket(): Promise<{ bucket: string; created: boolean; skipped: boolean }>;
+  /** Deploy the prebuilt classification worker for this environment. */
+  deployWorker(env: ManagedEnvironment): Promise<void>;
+  /**
+   * Create or drop the full-text index in this environment's app database, to match `search.fts`.
+   *
+   * A provisioning step rather than a migration, because the index is **derived** — every row in it
+   * comes from `pithy_support_messages` and `reindexThread` rebuilds it on demand. That is the line a
+   * migration is for: schema whose loss loses data. Keeping it here is also what makes the flag safe
+   * to toggle at all, since a config-conditional migration removed from the set is corruption to
+   * Kysely and blocks `pithy migrate` for every capability sharing the database.
+   */
+  ensureSearchIndex(env: ManagedEnvironment): Promise<{ created: boolean; dropped: boolean }>;
+  /**
+   * Ensure the inbound Email Routing rule that delivers the support address to the app worker.
+   * Idempotent, keyed on the rule name. Returns `skipped: true` when no routing config was supplied.
+   */
+  ensureRoutingRule(): Promise<{ created: boolean; skipped: boolean }>;
+}
+
+/** What provisioning produced. */
+export interface SupportProvisionResult {
+  /** The R2 bucket, and whether it had to be created. */
+  bucket: { bucket: string; created: boolean; skipped: boolean };
+  /** The environments a classification worker was deployed for. */
+  environments: ManagedEnvironment[];
+  /** What the full-text index did, per environment — created, dropped, or already correct. */
+  search: Array<{ env: ManagedEnvironment; created: boolean; dropped: boolean }>;
+  /** Whether the inbound routing rule was created, already present, or skipped. */
+  routing: { created: boolean; skipped: boolean };
+}
+
+/**
+ * Provision the support infrastructure.
+ *
+ * The order matters and is the inverse of how it fails: the bucket exists before a worker that could
+ * write to it, and **the routing rule is last** — creating it first would start delivering mail to a
+ * Worker whose classification host is not deployed yet, which is a window where real customer
+ * messages arrive and stay `uncategorized` with nothing to say why.
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export async function provisionSupport(
+  provisioner: SupportProvisioner,
+  environments: DeclaredEnvironments | readonly string[],
+): Promise<SupportProvisionResult> {
+  await provisioner.preflight();
+  const bucket = await provisioner.ensureBucket();
+  const search: SupportProvisionResult["search"] = [];
+  for (const env of managedEnvironments(environments)) {
+    await provisioner.deployWorker(env);
+    // Per environment, because each has its own app database — and after the worker, so a database
+    // that gains the index always has something able to write to it.
+    search.push({ env, ...(await provisioner.ensureSearchIndex(env)) });
+  }
+  const routing = await provisioner.ensureRoutingRule();
+  return { bucket, environments: managedEnvironments(environments), routing, search };
+}
+
+/** The teardown seam — the inverse of {@link SupportProvisioner}. Every step idempotent. */
+export interface SupportDeprovisioner {
+  /** Delete the env's classification worker. Idempotent. */
+  deleteWorker(env: ManagedEnvironment): Promise<void>;
+  /** Remove the inbound routing rule, so mail stops being delivered here. Idempotent. */
+  removeRoutingRule(): Promise<{ removed: boolean }>;
+  /**
+   * Delete the R2 bucket **and everything in it** — every attachment and every raw message an adopter's
+   * customers ever sent. Destructive, so the orchestration only calls it when explicitly asked.
+   */
+  deleteBucket(): Promise<void>;
+}
+
+/** Teardown options. By default the bucket is **kept**: it holds correspondence, not cache. */
+export interface SupportDeprovisionOptions {
+  /** Also delete the R2 bucket and its contents. Off by default. */
+  deleteStorage?: boolean;
+}
+
+/**
+ * Tear down the support infrastructure, reversing {@link provisionSupport}.
+ *
+ * The routing rule goes **first**, and that ordering is the whole point: stop new mail arriving before
+ * removing the workers that would have handled it, or messages land in a Worker with no classification
+ * host during the teardown. Stored correspondence is preserved unless explicitly requested — losing an
+ * adopter's support history to a teardown flag would be unrecoverable.
+ *
+ * `environments` is the project's declaration from the root `pithy.config.ts` (#241). Every declared
+ * environment is provisioned; an environment this skipped would be one the project deploys to with no
+ * resources behind it — the silence the closed `ManagedEnvironment` enum used to produce.
+ */
+export async function deprovisionSupport(
+  deprovisioner: SupportDeprovisioner,
+  environments: DeclaredEnvironments | readonly string[],
+  options: SupportDeprovisionOptions = {},
+): Promise<void> {
+  await deprovisioner.removeRoutingRule();
+  for (const env of managedEnvironments(environments)) {
+    await deprovisioner.deleteWorker(env);
+  }
+  if (options.deleteStorage) await deprovisioner.deleteBucket();
+}

package/src/provision/resolveSupportConfig.ts

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { hostWorkflowsFor, resolveWorkflowHost, type WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import type { SupportConfig } from "../config/config";
+import { SUPPORT_CAPABILITY, supportWorkflowRegistry } from "../workflows/specs";
+
+/**
+ * Resolve the support worker's committed `wrangler.jsonc` template into one environment's standalone
+ * config. Every per-environment decision lives here; everything static — the compatibility date, the
+ * AI binding, the Workflow class name — stays as the template committed it.
+ *
+ * Thin over core's {@link resolveWorkflowHost}, which owns the mechanics (clone, fill by binding name,
+ * stamp `ENVIRONMENT`). This file owns only what is support's: which binding maps to which provisioned
+ * resource, the Workflow name derived from support's own specs, and the serialized config the worker
+ * parses.
+ *
+ * **`AI` is marked remote.** Workflows cannot use remote bindings in general, so a host always runs
+ * locally under `wrangler dev` — and Workers AI has no local emulation, so without this flag the
+ * classification step has nothing to call in development. Same treatment `@pithy-sh/vector` gives
+ * Vectorize, for the same reason.
+ *
+ * There is no secrets binding and no secrets database, and that absence is deliberate: this worker
+ * reads a message and writes a classification. The AI binding is its entire dependency, so it holds no
+ * credential at all — which is the smallest blast radius a deployed worker can have.
+ */
+
+/** The resolved resource ids + per-env values for one environment's support-worker deploy. */
+export interface SupportConfigParams {
+  /**
+   * The project name — the `<project>` segment the deployed worker and its classification Workflow
+   * lead with. The root `pithy.config.ts` `name`, resolved by `requireProjectName` and never guessed.
+   */
+  project: string;
+  /** The target environment. */
+  env: ManagedEnvironment;
+  /** The app database id for this environment — where the support tables live. */
+  appDatabaseId: string;
+  /**
+   * The app's resolved support config, serialized into the worker's `SUPPORT_CONFIG` var.
+   *
+   * This is how an adopter's federated categories reach the prompt. The worker is deployed from this
+   * package and cannot import their code, so the taxonomy has to travel as data — which it does,
+   * because it always was data.
+   */
+  supportConfig: SupportConfig;
+}
+
+/** Fill the template for one environment. */
+export function resolveSupportConfig(
+  template: WorkflowHostTemplate,
+  params: SupportConfigParams,
+): WorkflowHostTemplate {
+  const { project, env } = params;
+  return resolveWorkflowHost(template, {
+    project,
+    capability: SUPPORT_CAPABILITY,
+    env,
+    databaseIds: { DB: params.appDatabaseId },
+    remoteBindings: ["AI"],
+    vars: { SUPPORT_CONFIG: JSON.stringify(params.supportConfig) },
+    // The classification Workflow, derived from support's own specs. A Workflow name is
+    // account-scoped, so it has to carry the project, and only the registry knows the job.
+    workflows: hostWorkflowsFor(supportWorkflowRegistry, { project, capability: SUPPORT_CAPABILITY, env }).workflows,
+  });
+}