create-ailk 0.1.0 → 0.1.1

package/templates/apps/api/src/services/aeo-score.ts

@@ -0,0 +1,288 @@
+/**
+ * Instant AEO score service (#4666 D3/D4).
+ *
+ * Productizes the existing pure `@working-theory/aeo` scorer behind the
+ * SSRF-guarded external-URL crawler at `@working-theory/aeo/fetch`. The
+ * rule set, severity table, and `identityMode`/`locale` defaults are
+ * declared ONCE, here.
+ */
+import {
+  runAudit,
+  schemaCoverage,
+  jsonldValidity,
+  entityMarkup,
+  faqHowtoIncentive,
+  EXAMPLE_SCORE_CRAWL,
+  EXAMPLE_SCORE_META,
+  EXAMPLE_SCORE_ANNOTATIONS,
+  type Rule,
+  type AuditReport,
+  type PerRuleResult,
+} from "@working-theory/aeo";
+import {
+  assertUrlSafe,
+  crawlSite,
+  buildAuditPayload,
+  type CrawlResult,
+  type FetchImpl,
+  type Resolver,
+  type SkippedEntry,
+} from "@working-theory/aeo/fetch";
+import type {
+  AeoDimension,
+  AeoDimensionId,
+  AeoScoreResult,
+} from "@working-theory/validation";
+
+/** The service's fixed rule set — the four content rules only (§ 2.1 FR4). */
+export const AEO_SCORE_RULES: Rule[] = [
+  schemaCoverage,
+  jsonldValidity,
+  entityMarkup,
+  faqHowtoIncentive,
+];
+
+/** Severity table, verbatim from prospect-audit-site's "Compose the score-led sales report". */
+export const AEO_DIMENSION_SEVERITY: Record<AeoDimensionId, "high" | "medium" | "low"> = {
+  "schema-coverage": "high",
+  "entity-markup": "high",
+  "jsonld-validity": "medium",
+  "faq-howto-incentive": "low",
+};
+
+const AEO_DIMENSION_LABELS: Record<AeoDimensionId, string> = {
+  "schema-coverage": "Schema Coverage",
+  "jsonld-validity": "JSON-LD Validity",
+  "entity-markup": "Entity Markup",
+  "faq-howto-incentive": "FAQ / HowTo Incentive",
+};
+
+/** D5 — the route's default + the configured-budget cap, both declared once. */
+export const AEO_SCORE_DEFAULT_BUDGET_MS = 6000;
+export const AEO_SCORE_MAX_BUDGET_MS = 15000;
+
+/**
+ * Resolve `AEO_SCORE_BUDGET_MS` for the route. A missing/unparseable/
+ * non-positive value falls back to the default silently (nothing to warn
+ * about — the env var is simply unset in dev). A value above the 15 000 ms
+ * cap is logged and falls back to the default (D5) — raising it beyond the
+ * crawler's own 15 s per-fetch bound would collide with the handler's 25 s
+ * request guard once cold start is added. Re-checked on EVERY request, not
+ * once at process startup — a serverless deployment has no persistent
+ * startup phase to check this at.
+ */
+export function resolveScoreBudgetMs(
+  rawEnv: string | undefined,
+  log?: { warn: (msg: string) => void },
+): number {
+  if (!rawEnv) return AEO_SCORE_DEFAULT_BUDGET_MS;
+  const parsed = Number(rawEnv);
+  if (!Number.isFinite(parsed) || parsed <= 0) return AEO_SCORE_DEFAULT_BUDGET_MS;
+  if (parsed > AEO_SCORE_MAX_BUDGET_MS) {
+    log?.warn(
+      `AEO_SCORE_BUDGET_MS=${rawEnv} exceeds the ${AEO_SCORE_MAX_BUDGET_MS}ms cap; falling back to the ${AEO_SCORE_DEFAULT_BUDGET_MS}ms default.`,
+    );
+    return AEO_SCORE_DEFAULT_BUDGET_MS;
+  }
+  return parsed;
+}
+
+const SEVERITY_RANK: Record<"high" | "medium" | "low", number> = {
+  high: 0,
+  medium: 1,
+  low: 2,
+};
+
+/** `lowestTwo` ordering (D4): score asc, then severity high>medium>low, then weight desc. */
+function compareDimensions(a: AeoDimension, b: AeoDimension): number {
+  if (a.score !== b.score) return a.score - b.score;
+  const severityDiff = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+  if (severityDiff !== 0) return severityDiff;
+  return b.weight - a.weight;
+}
+
+const FAQ_HOWTO_INCENTIVE_ID: AeoDimensionId = "faq-howto-incentive";
+
+/** The fixed opportunity sentence for the incentive dimension (D4) — its per-page results carry no evidence. */
+function faqHowtoOpportunityFinding(slug: string): string {
+  return `${slug}: no FAQPage or HowTo structured data (a visibility opportunity, not a defect)`;
+}
+
+function buildDimension(ruleId: AeoDimensionId, report: AuditReport): AeoDimension {
+  const perRule = report.perRule.find((r) => r.id === ruleId) as PerRuleResult;
+  const perPage = perRule.perPage ?? [];
+  const fraction = perRule.score ?? (perRule.pass ? 1 : 0);
+  const score = Math.round(fraction * 100);
+
+  let finding: string | null;
+  let pagesPassing: number;
+  const pagesTotal = perPage.length > 0 ? perPage.length : 1;
+
+  if (ruleId === FAQ_HOWTO_INCENTIVE_ID) {
+    pagesPassing = perPage.filter((p) => p.bonus === true).length;
+    const firstMissing = perPage.find((p) => p.bonus !== true);
+    finding = firstMissing ? faqHowtoOpportunityFinding(firstMissing.slug) : null;
+  } else {
+    pagesPassing = perPage.length > 0 ? perPage.filter((p) => p.pass).length : (perRule.pass ? 1 : 0);
+    const firstFailing = perPage.find((p) => !p.pass);
+    finding = firstFailing ? (firstFailing.evidence ?? perRule.evidence ?? null) : null;
+  }
+
+  return {
+    id: ruleId,
+    label: AEO_DIMENSION_LABELS[ruleId],
+    weight: perRule.weight,
+    score,
+    severity: AEO_DIMENSION_SEVERITY[ruleId],
+    finding,
+    pagesPassing,
+    pagesTotal,
+  };
+}
+
+/**
+ * `assertUrlSafe`'s per-path rejection text (`packages/aeo/src/fetch/ssrf.ts`)
+ * can disclose which internal host/IP a crawl target resolved to — an
+ * anonymous-endpoint recon primitive (AILK #5110, mirroring the #4707 fix
+ * already applied to `scoreUrl`'s top-level `unavailable`/`ssrf_blocked`
+ * check below). `crawlSite` re-checks every path individually (DNS-rebinding
+ * defense) and writes the raw `assertUrlSafe` text straight into
+ * `SkippedEntry.reason` (`packages/aeo/src/fetch/crawl.ts:125`) — deliberately
+ * so, per that file's own test
+ * (`packages/aeo/__tests__/fetch/crawl.test.ts:47-49`), so the redaction
+ * happens HERE instead, at the boundary where a `ready` result's
+ * `meta.skipped` is assembled. Every `assertUrlSafe` rejection message has
+ * one of these six fixed prefixes; `crawlSite`'s other `SkippedEntry.reason`
+ * producers (`"budget_exceeded"`, a `fetchPage` HTTP/redirect/fetch-failure
+ * message) never do.
+ */
+const SSRF_GUARD_REASON_PATTERN =
+  /^(Not a valid URL:|Only http\(s\) URLs allowed,|Blocked host \(internal\/loopback\/metadata\):|DNS resolution failed for|No DNS addresses resolved for|Host .+ resolves to a blocked address:)/;
+
+/**
+ * `meta.skipped[]` boundary serializer (#5110). A per-path SSRF-guard
+ * rejection is logged server-side (the specific host/IP detail, for operator
+ * diagnosis) and replaced on the wire with the same generic `"ssrf_blocked"`
+ * sentinel `scoreUrl`'s top-level check already returns (below) — never the
+ * raw text. Any other skip reason passes through unchanged.
+ */
+function toClientSkippedEntry(entry: SkippedEntry): SkippedEntry {
+  if (!SSRF_GUARD_REASON_PATTERN.test(entry.reason)) return entry;
+  console.warn("aeo-score: per-path SSRF-guard rejection (redacted on the wire)", {
+    path: entry.path,
+    url: entry.url,
+    reason: entry.reason,
+  });
+  return { ...entry, reason: "ssrf_blocked" };
+}
+
+/** Pure: crawl payload → runAudit → dimensions (D3/D4). Never throws on an empty crawl — the caller checks first. */
+export function scoreCrawl(
+  crawl: CrawlResult,
+  opts?: { now?: () => Date },
+): AeoScoreResult {
+  if (crawl.pages.length === 0) {
+    return {
+      status: "unavailable",
+      reason: "no_pages_fetched",
+      message: "No pages were fetched.",
+    };
+  }
+
+  const payload = buildAuditPayload(crawl.pages);
+  const report = runAudit(
+    { ...payload, locale: "en", identityMode: "organization" },
+    AEO_SCORE_RULES,
+  );
+
+  const dimensions = AEO_SCORE_RULES.map((rule) =>
+    buildDimension(rule.id as AeoDimensionId, report),
+  );
+  const lowestTwo = [...dimensions].sort(compareDimensions).slice(0, 2);
+  const partial = crawl.skipped.some((s) => s.reason === "budget_exceeded");
+  const now = opts?.now ? opts.now() : new Date();
+
+  return {
+    status: "ready",
+    score: Math.round(report.fractionalScore ?? report.score),
+    dimensions,
+    lowestTwo,
+    meta: {
+      auditedAt: now.toISOString(),
+      pagesAudited: crawl.pages.length,
+      partial,
+      skipped: crawl.skipped.map(toClientSkippedEntry),
+      schemaVersion: report.meta.schemaVersion,
+      registryVersion: report.meta.registryVersion,
+    },
+  };
+}
+
+export interface ScoreUrlDeps {
+  fetchImpl?: FetchImpl;
+  resolver?: Resolver;
+  budgetMs?: number;
+}
+
+/** `assertUrlSafe` → `crawlSite` → `scoreCrawl` (D3). */
+export async function scoreUrl(
+  url: string,
+  deps: ScoreUrlDeps = {},
+): Promise<AeoScoreResult> {
+  const safe = await assertUrlSafe(url, {
+    ...(deps.resolver !== undefined && { resolver: deps.resolver }),
+  });
+  if (!safe.ok) {
+    return { status: "unavailable", reason: "ssrf_blocked", message: safe.reason };
+  }
+
+  const budgetMs = deps.budgetMs ?? AEO_SCORE_DEFAULT_BUDGET_MS;
+  try {
+    const crawl = await crawlSite(url, {
+      ...(deps.fetchImpl !== undefined && { fetchImpl: deps.fetchImpl }),
+      ...(deps.resolver !== undefined && { resolver: deps.resolver }),
+      deadline: Date.now() + budgetMs,
+    });
+    if (crawl.pages.length === 0) {
+      return {
+        status: "unavailable",
+        reason: "no_pages_fetched",
+        message: "No pages were fetched within the crawl budget.",
+      };
+    }
+    return scoreCrawl(crawl);
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    return { status: "unavailable", reason: "crawl_failed", message };
+  }
+}
+
+/** The bundled pre-launch example — no runtime `fs` read (D6). */
+export function loadExampleScore(): AeoScoreResult {
+  const result = scoreCrawl(EXAMPLE_SCORE_CRAWL);
+  if (result.status !== "ready") {
+    // The fixture is committed and known-good; this should never happen.
+    throw new Error("Example score fixture failed to score.");
+  }
+  const annotate = (d: AeoDimension): AeoDimension => ({
+    ...d,
+    annotation: EXAMPLE_SCORE_ANNOTATIONS[d.id],
+  });
+  return {
+    ...result,
+    dimensions: result.dimensions.map(annotate),
+    lowestTwo: result.lowestTwo.map(annotate),
+    meta: {
+      ...result.meta,
+      example: true,
+      sourceUrl: EXAMPLE_SCORE_META.sourceUrl,
+      generatedAt: EXAMPLE_SCORE_META.generatedAt,
+      // Wire-visible disclosure (acceptance-review finding, #4666): whether
+      // the crawl data is a genuine fetch of `sourceUrl` or a hand-authored
+      // representative dataset. Sourced from EXAMPLE_SCORE_META itself, not
+      // hardcoded here, so regenerating the fixture from a real crawl flips
+      // this automatically.
+      illustrative: EXAMPLE_SCORE_META.illustrative,
+    },
+  };
+}

package/templates/apps/api/src/services/answer-distributions.ts

@@ -0,0 +1,138 @@
+/**
+ * @file answer-distributions.ts
+ * @description Shared per-question answer bucketing (#4771 D4).
+ *
+ * Extracted from `waitlist-dashboard.ts`'s `computeMetricRow` (the original
+ * inline `distributions` body) — moved verbatim, not rewritten, so
+ * `waitlist-dashboard.test.ts` stays green with NO edits to that file (the
+ * AC 7 regression floor).
+ *
+ * Takes already-flattened answer maps, not rows: `waitlist-dashboard.ts`
+ * passes `leads.map((l) => l.payload)`; `flow-aggregate.ts` passes
+ * `sessions.map((s) => flattenSessionState(s.state))`. That is what lets one
+ * implementation serve two different row types without either service
+ * knowing about the other's.
+ *
+ * Hosted as a THIRD, neutral module rather than inside `flow-aggregate.ts`
+ * (the issue's own `## Scope` names only that file) — a deliberate scope
+ * extension per `rules/worker-contract.md` § Mid-task scope expansion:
+ * hosting the shared helper in `flow-aggregate.ts` would make the operator
+ * dashboard import from the flow-aggregate service, an import direction no
+ * reader would predict from the names.
+ */
+
+import { logger } from "@working-theory/observability";
+import type { WaitlistAnswerType } from "@working-theory/validation";
+
+/**
+ * Defensive upper bound on an aggregation read (Medium finding, PR #4687
+ * security review). Caps the raw row count any SINGLE scoped read can
+ * return, so a `kind:"all"` aggregation spanning many sites (or a flow with
+ * many completed sessions) cannot load an unbounded result set into memory.
+ * Generous enough that no real deployment should hit it yet measured — if
+ * one does, the affected read undercounts rather than growing unbounded,
+ * and `logAggregationCapHit` below leaves a signal to act on (measure, then
+ * follow up with a real bound or DB-side aggregation).
+ */
+export const MAX_AGGREGATION_ROWS = 20_000;
+
+export function logAggregationCapHit(where: string, rowCount: number): void {
+  if (rowCount < MAX_AGGREGATION_ROWS) return;
+  logger.warn(
+    { where, rowCount, cap: MAX_AGGREGATION_ROWS },
+    "[answer-distributions] aggregation read hit its row cap — results may undercount",
+  );
+}
+
+/** A question's declared option set + the two fields the bucketer needs. */
+export type AnswerDistributionQuestion = {
+  id: string;
+  answerType: WaitlistAnswerType;
+  // `| undefined` (not just `?`) — the repo's `exactOptionalPropertyTypes`
+  // distinguishes "key absent" from "key present with value undefined", and
+  // both `WaitlistQuestion.options` and `WaitlistExperimentConfig`'s own
+  // `.optional()`-inferred fields are of the latter, wider shape.
+  options?: readonly { value: string }[] | undefined;
+};
+
+export type AnswerDistributionOption = {
+  value: string;
+  count: number;
+  share: number;
+};
+
+export type AnswerDistribution = {
+  questionId: string;
+  answerType: WaitlistAnswerType;
+  answered: number;
+  options: AnswerDistributionOption[];
+};
+
+/**
+ * Read one question's answer out of an already-flattened answer map — moved
+ * verbatim from `waitlist-dashboard.ts`'s (formerly local) `readPayloadAnswer`.
+ */
+export function readPayloadAnswer(
+  payload: unknown,
+  questionId: string,
+): string | string[] | undefined {
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const value = (payload as Record<string, unknown>)[questionId];
+  if (typeof value === "string" && value.length > 0) return value;
+  if (Array.isArray(value)) {
+    const strings = value.filter((v): v is string => typeof v === "string");
+    return strings.length > 0 ? strings : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Bucket every declared question's answers across a set of already-flattened
+ * answer maps — moved verbatim from `computeMetricRow`'s inline
+ * `distributions` body. A value outside a question's declared options is
+ * counted under `"(other)"`; `text` / `email` / `url` questions are never
+ * charted (empty `options`, `answered` still populated).
+ */
+export function computeAnswerDistributions(
+  questions: readonly AnswerDistributionQuestion[],
+  answerSets: readonly unknown[],
+): AnswerDistribution[] {
+  return questions.map((q) => {
+    const answeredSets = answerSets.filter(
+      (payload) => readPayloadAnswer(payload, q.id) !== undefined,
+    );
+    const answered = answeredSets.length;
+    if (
+      q.answerType === "text" ||
+      q.answerType === "email" ||
+      q.answerType === "url"
+    ) {
+      return {
+        questionId: q.id,
+        answerType: q.answerType,
+        answered,
+        options: [],
+      };
+    }
+    const declared = new Set((q.options ?? []).map((o) => o.value));
+    const counts = new Map<string, number>();
+    for (const payload of answeredSets) {
+      const value = readPayloadAnswer(payload, q.id);
+      const values = Array.isArray(value)
+        ? value
+        : value !== undefined
+          ? [value]
+          : [];
+      for (const v of values) {
+        const bucket = declared.has(v) ? v : "(other)";
+        counts.set(bucket, (counts.get(bucket) ?? 0) + 1);
+      }
+    }
+    const options = [...counts.entries()].map(([value, count]) => ({
+      value,
+      count,
+      share: answered > 0 ? count / answered : 0,
+    }));
+    return { questionId: q.id, answerType: q.answerType, answered, options };
+  });
+}