@getvitops/utils 8.2.0 → 8.3.0-alpha.0

package/dist/reviews/select.mjs

@@ -0,0 +1,3 @@
+import { i as selectReviews } from "../plan-DpHv6NO8.mjs";
+
+export { selectReviews };

package/dist/turnstile/index.d.mts

@@ -0,0 +1,105 @@
+/** A Turnstile widget as the list endpoint returns it. The list never carries the secret. */
+interface WidgetSummary {
+  sitekey: string;
+  name: string;
+  domains: string[];
+  mode: string;
+}
+/** What the config asks for. */
+interface TurnstileSetup {
+  /** Widget display name (not unique in Cloudflare). */
+  name: string;
+  /** Hostnames to protect; the widget also covers their subdomains. */
+  domains: string[];
+  /** `site.security.turnstile.siteKey`, when already set. */
+  siteKey?: string | undefined;
+}
+/** What the executor observed. */
+interface TurnstileState {
+  /** Undefined when no account could be resolved. */
+  accountId?: string | undefined;
+  widgets: WidgetSummary[];
+}
+type StepAction = 'create' | 'skip' | 'blocked';
+interface StepPlan {
+  action: StepAction;
+  detail: string;
+}
+interface TurnstilePlan {
+  /** Create the widget in Cloudflare. */
+  widget: StepPlan;
+  /** Write the public site key to `site.security.turnstile.siteKey`. */
+  config: StepPlan;
+  /** The widget the config should point at, when one already exists (adopted). */
+  adopt?: WidgetSummary | undefined;
+  /** Hostnames the created widget will cover. */
+  domains: string[];
+  /** What only a human can do — most importantly, where the secret goes. */
+  reminders: string[];
+}
+/** Cloudflare caps a widget at 10 domains; more is a plan-time refusal, not an API 400. */
+export declare const MAX_DOMAINS = 10;
+export declare function plan(setup: TurnstileSetup, state: TurnstileState): TurnstilePlan;
+/** Any step that isn't a skip — the live state or the config has drifted. */
+export declare function hasDrift(p: TurnstilePlan): boolean;
+export declare function formatPlan(p: TurnstilePlan): string;
+type StepStatus = 'created' | 'present' | 'blocked' | 'failed';
+interface TurnstileResult {
+  step: string;
+  status: StepStatus;
+  detail: string;
+}
+export declare function formatSummary(results: TurnstileResult[]): string;
+/**
+ * The account to create the widget in. `CLOUDFLARE_ACCOUNT_ID` wins; otherwise the token's
+ * only account. Cloudflare's docs state no permission for `GET /accounts`, so a token scoped
+ * to Turnstile alone may be refused here: the message says to set the id instead.
+ */
+export declare function resolveAccountId(token: string, explicit: string | undefined, fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  accountId?: string;
+  message?: string;
+}>;
+/** Every widget in the account, following pagination. */
+export declare function listWidgets(token: string, accountId: string, fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  widgets: WidgetSummary[];
+  message?: string;
+}>;
+/**
+ * Create a managed widget. **Create only** — the planner decides whether one is needed. The
+ * returned `secret` is the only time Cloudflare shows it; the caller must store it as a Worker
+ * secret and must not write it to a config file.
+ */
+export declare function createWidget(token: string, accountId: string, widget: {
+  name: string;
+  domains: string[];
+}, fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  sitekey?: string;
+  secret?: string;
+  message?: string;
+}>;
+/**
+ * Hostnames a widget should cover, from the site config: the canonical domain and every
+ * environment's URL. Cloudflare matches subdomains too, so `example.com` already covers
+ * `dev.example.com`. Deduplicated, lowercase, no scheme or port. `localhost` is never added:
+ * Cloudflare publishes always-pass test keys for local development.
+ */
+export declare function deriveDomains(site: {
+  domains?: {
+    canonical?: string | undefined;
+  } | undefined;
+  environments?: Record<string, {
+    url?: string | undefined;
+  } | undefined> | undefined;
+}): string[];
+/**
+ * Merge the site key into a **raw, on-disk** config object — the rule `ads setup`'s
+ * `patchRaw` follows: never write from the resolved object, so `extends` and shorthand
+ * shapes are not normalised into a copy nothing builds from. Everything outside
+ * `site.security.turnstile.siteKey` is left exactly as it was.
+ */
+export declare function patchSiteKey(raw: unknown, siteKey: string): unknown;
+export type { StepAction, StepPlan, StepStatus, TurnstilePlan, TurnstileResult, TurnstileSetup, TurnstileState, WidgetSummary };
+//# sourceMappingURL=index.d.mts.map

package/dist/turnstile/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/turnstile/types.ts","../../src/turnstile/plan.ts","../../src/turnstile/cloudflare.ts","../../src/turnstile/index.ts"],"mappings":";UACiB;EACf;EACA;EACA;EACA;;;UAIe;;EAEf;;EAEA;;EAEA;;;UAIe;;EAEf;EACA,SAAS;;KCJC;UAEK;EACf,QAAQ;EACR;;UAGe;;EAEf,QAAQ;;EAER,QAAQ;;EAER,QAAQ;;EAER;;EAEA;;;qBAIW;wBAKG,KAAK,OAAO,gBAAgB,OAAO,iBAAiB;;wBA4FpD,SAAS,GAAG;wBAMZ,WAAW,GAAG;KAUlB;UAEK;EACf;EACA,QAAQ;EACR;;wBAGc,cAAc,SAAS;;;;;;wBCpHjB,iBACpB,eACA,8BACA,mBAAkB,QACjB;EAAU;EAAa;EAAoB;;;wBAuBxB,YACpB,eACA,mBACA,mBAAkB,QACjB;EAAU;EAAa,SAAS;EAAiB;;;;;;;wBA2B9B,aACpB,eACA,mBACA;EAAU;EAAc;GACxB,mBAAkB,QACjB;EAAU;EAAa;EAAkB;EAAiB;;;;;;;;wBCrF7C,cAAc;EAC5B;IAAY;;EACZ,eAAe;IAAiB;;;;;;;;;wBA0BlB,aAAa,cAAc"}

package/dist/turnstile/index.mjs

@@ -0,0 +1,281 @@
+import { t as table } from "../plan-format-CIz6Feg2.mjs";
+
+// src/turnstile/plan.ts
+/**
+* Every decision `vitops setup turnstile` makes, as one pure function.
+*
+* Pure in the load-bearing sense: no `fetch`, no `fs`, no clock, no stdin. The
+* executor (`cloudflare.ts`) lists the account's widgets and creates the missing one;
+* this module decides, from that observation, what is left to do. The same split
+* `ads/plan.ts` and `onboarding/plan.ts` make, for the same two payoffs: `--dry` is a
+* *complete* account of a run, and `--check` is an honest drift report.
+*
+* Idempotency lives here. A widget that already covers the site's domains resolves
+* to `skip`, so a re-run is all skips by construction rather than by the executor
+* checking twice. And there is no update or delete verb anywhere in this module's
+* vocabulary: an existing widget is only ever *adopted* (its public site key is
+* written to the config), never edited, rotated or removed.
+*/
+/** Cloudflare caps a widget at 10 domains; more is a plan-time refusal, not an API 400. */
+const MAX_DOMAINS = 10;
+const covers = (w, domains) => domains.every((d) => w.domains.some((wd) => d === wd || d.endsWith(`.${wd}`)));
+function plan(setup, state) {
+	const reminders = ["Set the secret on the Worker: `npx wrangler secret put VITOPS_TURNSTILE_SECRET` (and on the dev worker with `--env`/`--config` as your setup uses). It is shown once, at creation, and never written to site.json."];
+	if (setup.domains.length === 0) return {
+		widget: {
+			action: "blocked",
+			detail: "no hostnames to protect — set site.domains.canonical or site.environments.<env>.url"
+		},
+		config: {
+			action: "blocked",
+			detail: "needs a widget first"
+		},
+		domains: [],
+		reminders: []
+	};
+	if (setup.domains.length > 10) return {
+		widget: {
+			action: "blocked",
+			detail: `${setup.domains.length} hostnames, but Cloudflare allows ${10} per widget`
+		},
+		config: {
+			action: "blocked",
+			detail: "needs a widget first"
+		},
+		domains: setup.domains,
+		reminders: []
+	};
+	if (!state.accountId) return {
+		widget: {
+			action: "blocked",
+			detail: "no Cloudflare account id — set CLOUDFLARE_ACCOUNT_ID (or use a token that can list accounts)"
+		},
+		config: {
+			action: "blocked",
+			detail: "needs a widget first"
+		},
+		domains: setup.domains,
+		reminders: []
+	};
+	const configured = setup.siteKey ? state.widgets.find((w) => w.sitekey === setup.siteKey) : void 0;
+	if (setup.siteKey && !configured) return {
+		widget: {
+			action: "blocked",
+			detail: `site.security.turnstile.siteKey ${setup.siteKey} matches no widget in this account — remove it to let setup adopt or create one`
+		},
+		config: {
+			action: "blocked",
+			detail: "config key is unverified"
+		},
+		domains: setup.domains,
+		reminders: []
+	};
+	const existing = configured ?? state.widgets.find((w) => covers(w, setup.domains));
+	if (existing) {
+		const uncovered = setup.domains.filter((d) => !covers(existing, [d]));
+		return {
+			widget: {
+				action: "skip",
+				detail: uncovered.length === 0 ? `widget "${existing.name}" already covers ${setup.domains.join(", ")}` : `widget "${existing.name}" exists but does not cover ${uncovered.join(", ")} — add them in the dashboard; this command never edits a widget`
+			},
+			config: setup.siteKey === existing.sitekey ? {
+				action: "skip",
+				detail: "site key already in site.json"
+			} : {
+				action: "create",
+				detail: `write ${existing.sitekey} to site.json`
+			},
+			adopt: existing,
+			domains: setup.domains,
+			reminders: ["The secret of an existing widget cannot be read back. Lost it? Rotate it in the dashboard (Turnstile > the widget > Rotate secret), then `wrangler secret put VITOPS_TURNSTILE_SECRET`."]
+		};
+	}
+	return {
+		widget: {
+			action: "create",
+			detail: `create "${setup.name}" (managed) for ${setup.domains.join(", ")}`
+		},
+		config: {
+			action: "create",
+			detail: "write the new site key to site.json"
+		},
+		domains: setup.domains,
+		reminders
+	};
+}
+/** Any step that isn't a skip — the live state or the config has drifted. */
+function hasDrift(p) {
+	return p.widget.action !== "skip" || p.config.action !== "skip";
+}
+const GLYPH = {
+	create: "+",
+	skip: "·",
+	blocked: "!"
+};
+function formatPlan(p) {
+	const rows = [["widget", p.widget], ["config", p.config]].map(([name, step]) => [
+		GLYPH[step.action],
+		name,
+		step.detail
+	]);
+	return table([
+		"",
+		"step",
+		"detail"
+	], rows, p.reminders);
+}
+function formatSummary(results) {
+	return table([
+		"step",
+		"status",
+		"detail"
+	], results.map((r) => [
+		r.step,
+		r.status,
+		r.detail
+	]), []);
+}
+
+// src/turnstile/cloudflare.ts
+const API = "https://api.cloudflare.com/client/v4";
+const cfError = (status, body) => {
+	const first = body.errors?.[0];
+	return first ? `${first.code} ${first.message}` : `HTTP ${status}`;
+};
+const PERMISSION_HINT = " (does the token carry Account > Turnstile > Edit?)";
+async function json(res) {
+	try {
+		return await res.json();
+	} catch {
+		return { success: false };
+	}
+}
+/**
+* The account to create the widget in. `CLOUDFLARE_ACCOUNT_ID` wins; otherwise the token's
+* only account. Cloudflare's docs state no permission for `GET /accounts`, so a token scoped
+* to Turnstile alone may be refused here: the message says to set the id instead.
+*/
+async function resolveAccountId(token, explicit, fetchImpl = fetch) {
+	if (explicit) return {
+		ok: true,
+		accountId: explicit
+	};
+	const res = await fetchImpl(`${API}/accounts?per_page=5`, { headers: { authorization: `Bearer ${token}` } });
+	const body = await json(res);
+	if (!res.ok || !body.success) return {
+		ok: false,
+		message: `${cfError(res.status, body)} — set CLOUDFLARE_ACCOUNT_ID to skip the account lookup`
+	};
+	const accounts = body.result ?? [];
+	if (accounts.length === 1) return {
+		ok: true,
+		accountId: accounts[0].id
+	};
+	return {
+		ok: false,
+		message: accounts.length === 0 ? "the token can see no accounts — set CLOUDFLARE_ACCOUNT_ID" : `the token can see ${accounts.length} accounts — set CLOUDFLARE_ACCOUNT_ID to choose one`
+	};
+}
+/** Every widget in the account, following pagination. */
+async function listWidgets(token, accountId, fetchImpl = fetch) {
+	const widgets = [];
+	for (let page = 1; page <= 20; page++) {
+		const res = await fetchImpl(`${API}/accounts/${encodeURIComponent(accountId)}/challenges/widgets?page=${page}&per_page=100`, { headers: { authorization: `Bearer ${token}` } });
+		const body = await json(res);
+		if (!res.ok || !body.success) return {
+			ok: false,
+			widgets: [],
+			message: cfError(res.status, body) + (res.status === 403 ? PERMISSION_HINT : "")
+		};
+		for (const w of body.result ?? []) widgets.push({
+			sitekey: w.sitekey,
+			name: w.name,
+			domains: w.domains ?? [],
+			mode: w.mode
+		});
+		const info = body.result_info;
+		if (!info || page * info.per_page >= info.total_count) break;
+	}
+	return {
+		ok: true,
+		widgets
+	};
+}
+/**
+* Create a managed widget. **Create only** — the planner decides whether one is needed. The
+* returned `secret` is the only time Cloudflare shows it; the caller must store it as a Worker
+* secret and must not write it to a config file.
+*/
+async function createWidget(token, accountId, widget, fetchImpl = fetch) {
+	const res = await fetchImpl(`${API}/accounts/${encodeURIComponent(accountId)}/challenges/widgets`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json"
+		},
+		body: JSON.stringify({
+			name: widget.name,
+			domains: widget.domains,
+			mode: "managed"
+		})
+	});
+	const body = await json(res);
+	if (!res.ok || !body.success || !body.result?.sitekey || !body.result.secret) return {
+		ok: false,
+		message: cfError(res.status, body) + (res.status === 403 ? PERMISSION_HINT : "")
+	};
+	return {
+		ok: true,
+		sitekey: body.result.sitekey,
+		secret: body.result.secret
+	};
+}
+
+// src/turnstile/index.ts
+/**
+* Hostnames a widget should cover, from the site config: the canonical domain and every
+* environment's URL. Cloudflare matches subdomains too, so `example.com` already covers
+* `dev.example.com`. Deduplicated, lowercase, no scheme or port. `localhost` is never added:
+* Cloudflare publishes always-pass test keys for local development.
+*/
+function deriveDomains(site) {
+	const urls = [site.domains?.canonical, ...Object.values(site.environments ?? {}).map((e) => e?.url)];
+	const hosts = /* @__PURE__ */ new Set();
+	for (const url of urls) {
+		if (!url) continue;
+		try {
+			const host = new URL(url).hostname.toLowerCase();
+			if (host && host !== "localhost") hosts.add(host);
+		} catch {}
+	}
+	return [...hosts].filter((h) => ![...hosts].some((p) => p !== h && h.endsWith(`.${p}`)));
+}
+/**
+* Merge the site key into a **raw, on-disk** config object — the rule `ads setup`'s
+* `patchRaw` follows: never write from the resolved object, so `extends` and shorthand
+* shapes are not normalised into a copy nothing builds from. Everything outside
+* `site.security.turnstile.siteKey` is left exactly as it was.
+*/
+function patchSiteKey(raw, siteKey) {
+	if (typeof raw !== "object" || raw == null || Array.isArray(raw)) throw new Error("config is not an object");
+	const root = raw;
+	const site = root["site"] ?? {};
+	const security = site["security"] ?? {};
+	const turnstile = security["turnstile"] ?? {};
+	return {
+		...root,
+		site: {
+			...site,
+			security: {
+				...security,
+				turnstile: {
+					...turnstile,
+					siteKey
+				}
+			}
+		}
+	};
+}
+
+export { MAX_DOMAINS, createWidget, deriveDomains, formatPlan, formatSummary, hasDrift, listWidgets, patchSiteKey, plan, resolveAccountId };
+//# sourceMappingURL=index.mjs.map

package/dist/turnstile/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/turnstile/plan.ts","../../src/turnstile/cloudflare.ts","../../src/turnstile/index.ts"],"sourcesContent":["/**\n * Every decision `vitops setup turnstile` makes, as one pure function.\n *\n * Pure in the load-bearing sense: no `fetch`, no `fs`, no clock, no stdin. The\n * executor (`cloudflare.ts`) lists the account's widgets and creates the missing one;\n * this module decides, from that observation, what is left to do. The same split\n * `ads/plan.ts` and `onboarding/plan.ts` make, for the same two payoffs: `--dry` is a\n * *complete* account of a run, and `--check` is an honest drift report.\n *\n * Idempotency lives here. A widget that already covers the site's domains resolves\n * to `skip`, so a re-run is all skips by construction rather than by the executor\n * checking twice. And there is no update or delete verb anywhere in this module's\n * vocabulary: an existing widget is only ever *adopted* (its public site key is\n * written to the config), never edited, rotated or removed.\n */\nimport { table } from '../plan-format.ts';\nimport type { TurnstileSetup, TurnstileState, WidgetSummary } from './types.ts';\n\nexport type StepAction = 'create' | 'skip' | 'blocked';\n\nexport interface StepPlan {\n  action: StepAction;\n  detail: string;\n}\n\nexport interface TurnstilePlan {\n  /** Create the widget in Cloudflare. */\n  widget: StepPlan;\n  /** Write the public site key to `site.security.turnstile.siteKey`. */\n  config: StepPlan;\n  /** The widget the config should point at, when one already exists (adopted). */\n  adopt?: WidgetSummary | undefined;\n  /** Hostnames the created widget will cover. */\n  domains: string[];\n  /** What only a human can do — most importantly, where the secret goes. */\n  reminders: string[];\n}\n\n/** Cloudflare caps a widget at 10 domains; more is a plan-time refusal, not an API 400. */\nexport const MAX_DOMAINS = 10;\n\nconst covers = (w: WidgetSummary, domains: string[]): boolean =>\n  domains.every((d) => w.domains.some((wd) => d === wd || d.endsWith(`.${wd}`)));\n\nexport function plan(setup: TurnstileSetup, state: TurnstileState): TurnstilePlan {\n  const reminders = [\n    'Set the secret on the Worker: `npx wrangler secret put VITOPS_TURNSTILE_SECRET` (and on the dev worker with `--env`/`--config` as your setup uses). It is shown once, at creation, and never written to site.json.',\n  ];\n\n  if (setup.domains.length === 0)\n    return {\n      widget: {\n        action: 'blocked',\n        detail:\n          'no hostnames to protect — set site.domains.canonical or site.environments.<env>.url',\n      },\n      config: { action: 'blocked', detail: 'needs a widget first' },\n      domains: [],\n      reminders: [],\n    };\n  if (setup.domains.length > MAX_DOMAINS)\n    return {\n      widget: {\n        action: 'blocked',\n        detail: `${setup.domains.length} hostnames, but Cloudflare allows ${MAX_DOMAINS} per widget`,\n      },\n      config: { action: 'blocked', detail: 'needs a widget first' },\n      domains: setup.domains,\n      reminders: [],\n    };\n\n  if (!state.accountId)\n    return {\n      widget: {\n        action: 'blocked',\n        detail:\n          'no Cloudflare account id — set CLOUDFLARE_ACCOUNT_ID (or use a token that can list accounts)',\n      },\n      config: { action: 'blocked', detail: 'needs a widget first' },\n      domains: setup.domains,\n      reminders: [],\n    };\n\n  // The config's own key wins: if it names a widget in this account, that is the one.\n  const configured = setup.siteKey\n    ? state.widgets.find((w) => w.sitekey === setup.siteKey)\n    : undefined;\n  if (setup.siteKey && !configured) {\n    // A key that no widget in this account owns is drift (typo, another account, a deleted\n    // widget). Creating a second widget would hide it, so stop and say so.\n    return {\n      widget: {\n        action: 'blocked',\n        detail: `site.security.turnstile.siteKey ${setup.siteKey} matches no widget in this account — remove it to let setup adopt or create one`,\n      },\n      config: { action: 'blocked', detail: 'config key is unverified' },\n      domains: setup.domains,\n      reminders: [],\n    };\n  }\n\n  const existing = configured ?? state.widgets.find((w) => covers(w, setup.domains));\n  if (existing) {\n    const uncovered = setup.domains.filter((d) => !covers(existing, [d]));\n    return {\n      widget: {\n        action: 'skip',\n        detail:\n          uncovered.length === 0\n            ? `widget \"${existing.name}\" already covers ${setup.domains.join(', ')}`\n            : `widget \"${existing.name}\" exists but does not cover ${uncovered.join(', ')} — add them in the dashboard; this command never edits a widget`,\n      },\n      config:\n        setup.siteKey === existing.sitekey\n          ? { action: 'skip', detail: 'site key already in site.json' }\n          : { action: 'create', detail: `write ${existing.sitekey} to site.json` },\n      adopt: existing,\n      domains: setup.domains,\n      reminders: [\n        'The secret of an existing widget cannot be read back. Lost it? Rotate it in the dashboard (Turnstile > the widget > Rotate secret), then `wrangler secret put VITOPS_TURNSTILE_SECRET`.',\n      ],\n    };\n  }\n\n  return {\n    widget: {\n      action: 'create',\n      detail: `create \"${setup.name}\" (managed) for ${setup.domains.join(', ')}`,\n    },\n    config: { action: 'create', detail: 'write the new site key to site.json' },\n    domains: setup.domains,\n    reminders,\n  };\n}\n\n/** Any step that isn't a skip — the live state or the config has drifted. */\nexport function hasDrift(p: TurnstilePlan): boolean {\n  return p.widget.action !== 'skip' || p.config.action !== 'skip';\n}\n\nconst GLYPH: Record<StepAction, string> = { create: '+', skip: '·', blocked: '!' };\n\nexport function formatPlan(p: TurnstilePlan): string {\n  const rows = (\n    [\n      ['widget', p.widget],\n      ['config', p.config],\n    ] as const\n  ).map(([name, step]) => [GLYPH[step.action], name, step.detail]);\n  return table(['', 'step', 'detail'], rows, p.reminders);\n}\n\nexport type StepStatus = 'created' | 'present' | 'blocked' | 'failed';\n\nexport interface TurnstileResult {\n  step: string;\n  status: StepStatus;\n  detail: string;\n}\n\nexport function formatSummary(results: TurnstileResult[]): string {\n  return table(\n    ['step', 'status', 'detail'],\n    results.map((r) => [r.step, r.status, r.detail]),\n    [],\n  );\n}\n","/**\n * Cloudflare's Turnstile widget API — the one thing `vitops setup turnstile` writes.\n *\n * Verified against developers.cloudflare.com (2026-11): list is\n * `GET /accounts/{id}/challenges/widgets` (paged, `per_page` 5 to 1000), create is\n * `POST` to the same path with `name`, `domains` (max 10) and `mode` required, and only\n * the create response carries `secret`. The token needs the **Account > Turnstile > Edit**\n * permission (API reference names: `Turnstile Sites Write`, or `Account Settings Write`).\n *\n * As in `onboarding/cloudflare.ts` there is deliberately no update, rotate or delete verb:\n * the destructive operations are absent rather than guarded. `fetchImpl` is injected and\n * every call returns a structured result rather than throwing.\n */\nimport type { WidgetSummary } from './types.ts';\n\nconst API = 'https://api.cloudflare.com/client/v4';\n\ninterface CfEnvelope<T> {\n  success: boolean;\n  errors?: { code: number; message: string }[];\n  result?: T;\n  result_info?: { page: number; per_page: number; total_count: number };\n}\n\nconst cfError = (status: number, body: CfEnvelope<unknown>): string => {\n  const first = body.errors?.[0];\n  return first ? `${first.code} ${first.message}` : `HTTP ${status}`;\n};\n\nconst PERMISSION_HINT = ' (does the token carry Account > Turnstile > Edit?)';\n\nasync function json<T>(res: Response): Promise<CfEnvelope<T>> {\n  try {\n    return (await res.json()) as CfEnvelope<T>;\n  } catch {\n    return { success: false };\n  }\n}\n\n/**\n * The account to create the widget in. `CLOUDFLARE_ACCOUNT_ID` wins; otherwise the token's\n * only account. Cloudflare's docs state no permission for `GET /accounts`, so a token scoped\n * to Turnstile alone may be refused here: the message says to set the id instead.\n */\nexport async function resolveAccountId(\n  token: string,\n  explicit: string | undefined,\n  fetchImpl: typeof fetch = fetch,\n): Promise<{ ok: boolean; accountId?: string; message?: string }> {\n  if (explicit) return { ok: true, accountId: explicit };\n  const res = await fetchImpl(`${API}/accounts?per_page=5`, {\n    headers: { authorization: `Bearer ${token}` },\n  });\n  const body = await json<{ id: string; name: string }[]>(res);\n  if (!res.ok || !body.success)\n    return {\n      ok: false,\n      message: `${cfError(res.status, body)} — set CLOUDFLARE_ACCOUNT_ID to skip the account lookup`,\n    };\n  const accounts = body.result ?? [];\n  if (accounts.length === 1) return { ok: true, accountId: accounts[0]!.id };\n  return {\n    ok: false,\n    message:\n      accounts.length === 0\n        ? 'the token can see no accounts — set CLOUDFLARE_ACCOUNT_ID'\n        : `the token can see ${accounts.length} accounts — set CLOUDFLARE_ACCOUNT_ID to choose one`,\n  };\n}\n\n/** Every widget in the account, following pagination. */\nexport async function listWidgets(\n  token: string,\n  accountId: string,\n  fetchImpl: typeof fetch = fetch,\n): Promise<{ ok: boolean; widgets: WidgetSummary[]; message?: string }> {\n  const widgets: WidgetSummary[] = [];\n  for (let page = 1; page <= 20; page++) {\n    const res = await fetchImpl(\n      `${API}/accounts/${encodeURIComponent(accountId)}/challenges/widgets?page=${page}&per_page=100`,\n      { headers: { authorization: `Bearer ${token}` } },\n    );\n    const body = await json<WidgetSummary[]>(res);\n    if (!res.ok || !body.success)\n      return {\n        ok: false,\n        widgets: [],\n        message: cfError(res.status, body) + (res.status === 403 ? PERMISSION_HINT : ''),\n      };\n    for (const w of body.result ?? [])\n      widgets.push({ sitekey: w.sitekey, name: w.name, domains: w.domains ?? [], mode: w.mode });\n    const info = body.result_info;\n    if (!info || page * info.per_page >= info.total_count) break;\n  }\n  return { ok: true, widgets };\n}\n\n/**\n * Create a managed widget. **Create only** — the planner decides whether one is needed. The\n * returned `secret` is the only time Cloudflare shows it; the caller must store it as a Worker\n * secret and must not write it to a config file.\n */\nexport async function createWidget(\n  token: string,\n  accountId: string,\n  widget: { name: string; domains: string[] },\n  fetchImpl: typeof fetch = fetch,\n): Promise<{ ok: boolean; sitekey?: string; secret?: string; message?: string }> {\n  const res = await fetchImpl(\n    `${API}/accounts/${encodeURIComponent(accountId)}/challenges/widgets`,\n    {\n      method: 'POST',\n      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },\n      body: JSON.stringify({ name: widget.name, domains: widget.domains, mode: 'managed' }),\n    },\n  );\n  const body = await json<{ sitekey: string; secret: string }>(res);\n  if (!res.ok || !body.success || !body.result?.sitekey || !body.result.secret)\n    return {\n      ok: false,\n      message: cfError(res.status, body) + (res.status === 403 ? PERMISSION_HINT : ''),\n    };\n  return { ok: true, sitekey: body.result.sitekey, secret: body.result.secret };\n}\n","/**\n * `vitops setup turnstile` — create a Cloudflare Turnstile widget and record its public site\n * key in `site.json`.\n *\n * A separate subpath (`@getvitops/utils/turnstile`), matching `./ads` and `./hosting`. It is\n * build-time tooling, unlike `@getvitops/utils/security` (the Worker-side verifier): keep the\n * two apart so a conversion route never pulls this in.\n *\n * The layering is the repo's usual one: `plan.ts` decides everything and touches nothing;\n * `cloudflare.ts` executes and decides nothing.\n */\nexport { MAX_DOMAINS, formatPlan, formatSummary, hasDrift, plan } from './plan.ts';\nexport type { StepAction, StepPlan, StepStatus, TurnstilePlan, TurnstileResult } from './plan.ts';\nexport { createWidget, listWidgets, resolveAccountId } from './cloudflare.ts';\nexport type { TurnstileSetup, TurnstileState, WidgetSummary } from './types.ts';\n\n/**\n * Hostnames a widget should cover, from the site config: the canonical domain and every\n * environment's URL. Cloudflare matches subdomains too, so `example.com` already covers\n * `dev.example.com`. Deduplicated, lowercase, no scheme or port. `localhost` is never added:\n * Cloudflare publishes always-pass test keys for local development.\n */\nexport function deriveDomains(site: {\n  domains?: { canonical?: string | undefined } | undefined;\n  environments?: Record<string, { url?: string | undefined } | undefined> | undefined;\n}): string[] {\n  const urls = [\n    site.domains?.canonical,\n    ...Object.values(site.environments ?? {}).map((e) => e?.url),\n  ];\n  const hosts = new Set<string>();\n  for (const url of urls) {\n    if (!url) continue;\n    try {\n      const host = new URL(url).hostname.toLowerCase();\n      if (host && host !== 'localhost') hosts.add(host);\n    } catch {\n      // a malformed URL is the config validator's business, not a reason to create a widget for it\n    }\n  }\n  // Drop hostnames already covered by a parent in the set (dev.example.com under example.com).\n  return [...hosts].filter((h) => ![...hosts].some((p) => p !== h && h.endsWith(`.${p}`)));\n}\n\n/**\n * Merge the site key into a **raw, on-disk** config object — the rule `ads setup`'s\n * `patchRaw` follows: never write from the resolved object, so `extends` and shorthand\n * shapes are not normalised into a copy nothing builds from. Everything outside\n * `site.security.turnstile.siteKey` is left exactly as it was.\n */\nexport function patchSiteKey(raw: unknown, siteKey: string): unknown {\n  if (typeof raw !== 'object' || raw == null || Array.isArray(raw))\n    throw new Error('config is not an object');\n  const root = raw as Record<string, unknown>;\n  const site = (root['site'] ?? {}) as Record<string, unknown>;\n  const security = (site['security'] ?? {}) as Record<string, unknown>;\n  const turnstile = (security['turnstile'] ?? {}) as Record<string, unknown>;\n  return {\n    ...root,\n    site: { ...site, security: { ...security, turnstile: { ...turnstile, siteKey } } },\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getvitops/utils",
-  "version": "8.2.0",
+  "version": "8.3.0-alpha.0",
   "description": "Shared build-time utilities for the Vitops toolchain — favicon generation and friends.",
   "homepage": "https://docs.vitops.ca",
   "bugs": "https://github.com/getvitops/design-system/issues",
@@ -50,10 +50,22 @@
       "types": "./dist/reviews/index.d.mts",
       "import": "./dist/reviews/index.mjs"
     },
+    "./turnstile": {
+      "types": "./dist/turnstile/index.d.mts",
+      "import": "./dist/turnstile/index.mjs"
+    },
+    "./reviews/select": {
+      "types": "./dist/reviews/select.d.mts",
+      "import": "./dist/reviews/select.mjs"
+    },
     "./ads": {
       "types": "./dist/ads/index.d.mts",
       "import": "./dist/ads/index.mjs"
     },
+    "./audit": {
+      "types": "./dist/audit/index.d.mts",
+      "import": "./dist/audit/index.mjs"
+    },
     "./media": {
       "types": "./dist/media/index.d.mts",
       "import": "./dist/media/index.mjs"
@@ -95,13 +107,33 @@
     "access": "public"
   },
   "dependencies": {
-    "@getvitops/config": "8.2.0",
+    "@getvitops/config": "8.3.0-alpha.0",
     "colorjs.io": "^0.5.2",
     "parse5": "^7.3.0",
     "png-to-ico": "^3.0.2",
     "sharp": "^0.35.3"
   },
-  "devDependencies": {},
+  "devDependencies": {
+    "@axe-core/playwright": "^4.10.0",
+    "lighthouse": "^13.0.0",
+    "playwright": "^1.62.1"
+  },
+  "peerDependencies": {
+    "@axe-core/playwright": ">=4.10.0",
+    "lighthouse": ">=13.0.0",
+    "playwright": ">=1.50.0"
+  },
+  "peerDependenciesMeta": {
+    "@axe-core/playwright": {
+      "optional": true
+    },
+    "lighthouse": {
+      "optional": true
+    },
+    "playwright": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=24"
   }