@salesforce/storefront-next-dev 1.5.0-alpha.0 → 1.5.0-alpha.1

package/dist/events.js

@@ -1,515 +1,7 @@
-import { n as sanitizeText, r as sanitizeUrl, t as sanitizeJsonValue } from "./sanitize.js";
-import { a as MIN_RECOMMENDED_BYTES, o as bundleAnalysisSchema } from "./schema.js";
-import path from "node:path";
-import { appendFile, readFile, readdir } from "node:fs/promises";
+import { _ as GUIDANCE, v as sanitizeJsonValue } from "./results.js";
+import { appendFile, readFile } from "node:fs/promises";
 import { z } from "zod";
 
-//#region src/audit/guidance.ts
-/**
-* Copyright 2026 Salesforce, Inc.
-*
-* Licensed under the Apache License, Version 2.0 (the "License");
-* you may not use this file except in compliance with the License.
-* You may obtain a copy of the License at
-*
-*     http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*/
-const GUIDANCE = [
-	"go",
-	"go-with-fixes",
-	"no-go"
-];
-/** Launch guidance from the known findings: critical blocks launch, high or medium needs fixes. */
-function guidanceFor(evaluations) {
-	const severities = new Set(evaluations.filter((item) => item.disposition === "finding").map((item) => item.severity));
-	if (severities.has("critical")) return "no-go";
-	return severities.has("high") || severities.has("medium") ? "go-with-fixes" : "go";
-}
-
-//#endregion
-//#region src/audit/runs.ts
-const RUNS_DIR = "runs";
-const RUN_ID = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z$/;
-/** `2026-10-14T10:26:00.123Z` → `2026-10-14T10-26-00Z`, safe as a folder name. */
-function runIdFor(startedAt) {
-	return startedAt.replace(/\.\d+Z$/, "Z").replaceAll(":", "-");
-}
-function runDir(workspace, id) {
-	if (!RUN_ID.test(id)) throw new Error(`Invalid run id: ${id}`);
-	return path.join(workspace, RUNS_DIR, id);
-}
-/** Run ids in the workspace, newest first. */
-async function listRuns(workspace) {
-	let entries;
-	try {
-		entries = await readdir(path.join(workspace, RUNS_DIR), { withFileTypes: true });
-	} catch (error) {
-		if (error.code === "ENOENT") return [];
-		throw error;
-	}
-	return entries.filter((entry) => entry.isDirectory() && RUN_ID.test(entry.name)).map((entry) => entry.name).sort().reverse();
-}
-/** The latest run's folder; throws when the workspace has no runs yet. */
-async function latestRunDir(workspace) {
-	const [latest] = await listRuns(workspace);
-	if (!latest) throw new Error(`${workspace} has no audit runs; run prepare first`);
-	return runDir(workspace, latest);
-}
-
-//#endregion
-//#region src/audit/results.ts
-/** Archive file name of the per-page Lighthouse HTML report. When present it is
-* recorded in `artifacts` as `{ available: true }` and served by the dashboard
-* server rather than embedded. ui/src/panels/Performance.tsx repeats this name. */
-const LIGHTHOUSE_REPORT = "report-mobile-cold.html";
-/** The workspace's prepared.json, written by `prepare` and read by `finalize` and the dashboard server. */
-const preparedSchema = z.object({
-	schemaVersion: z.literal("1.0"),
-	run: z.object({
-		id: z.string().regex(RUN_ID),
-		generatedAt: z.string().datetime(),
-		toolVersion: z.string(),
-		playhouseVersion: z.string().optional()
-	}).strict(),
-	project: z.object({
-		root: z.string(),
-		packageName: z.string().optional()
-	}).strict(),
-	instructions: z.string().optional(),
-	pages: z.array(z.object({
-		label: z.string(),
-		url: z.string(),
-		archiveDir: z.string()
-	}).strict()),
-	pageFailures: z.array(z.object({
-		label: z.string(),
-		url: z.string(),
-		error: z.string()
-	}).strict()).optional(),
-	expectedPages: z.array(z.string()).optional(),
-	coverage: z.array(z.object({
-		page: z.string(),
-		status: z.literal("missing"),
-		note: z.string()
-	}).strict()).optional().default([]),
-	rules: z.array(z.object({
-		ruleId: z.string(),
-		title: z.string(),
-		file: z.string(),
-		data: z.string().optional(),
-		output: z.string()
-	}).strict()),
-	decidedFindings: z.array(z.object({
-		ruleId: z.string(),
-		title: z.string(),
-		severity: z.string(),
-		summary: z.string()
-	}).strict())
-}).strict();
-function parsePrepared(value) {
-	const parsed = preparedSchema.safeParse(value);
-	if (!parsed.success) throw new Error(`prepared.json is invalid: ${parsed.error.message}`);
-	return parsed.data;
-}
-const evidenceSchema = z.discriminatedUnion("type", [
-	z.object({
-		type: z.literal("source"),
-		file: z.string(),
-		line: z.number().int().positive().optional(),
-		excerpt: z.string().optional()
-	}),
-	z.object({
-		type: z.literal("playhouse"),
-		page: z.string(),
-		artifact: z.string(),
-		pointer: z.string().optional(),
-		value: z.union([
-			z.string(),
-			z.number(),
-			z.boolean()
-		]).optional()
-	}),
-	z.object({
-		type: z.literal("manual"),
-		description: z.string(),
-		location: z.string().optional()
-	})
-]);
-/** The one rule whose evaluation may carry a `waterfall`: the per-page server request graph drawn on the Performance tab. */
-const WATERFALL_RULE_ID = "performance/server-request-waterfall";
-const waterfallStepSchema = z.object({
-	id: z.string().regex(/^[a-z0-9-]+$/),
-	kind: z.enum([
-		"middleware",
-		"loader",
-		"api",
-		"render"
-	]),
-	label: z.string().min(1),
-	service: z.enum([
-		"scapi",
-		"slas",
-		"ocapi",
-		"einstein",
-		"data-store",
-		"other"
-	]).optional(),
-	source: z.object({
-		file: z.string(),
-		line: z.number().int().positive().optional()
-	}).strict(),
-	after: z.array(z.string()).default([]),
-	blocking: z.boolean(),
-	conditional: z.string().optional(),
-	note: z.string().optional(),
-	critical: z.boolean().optional(),
-	opportunity: z.enum([
-		"parallelize",
-		"scapi-hook",
-		"stream"
-	]).optional()
-}).strict();
-const waterfallSchema = z.object({ pages: z.array(z.object({
-	page: z.string(),
-	route: z.string(),
-	summary: z.string(),
-	steps: z.array(waterfallStepSchema).min(1).max(60)
-}).strict()) }).strict();
-/** The one rule whose evaluation may carry `recommendations`: the AI's suggestions in the Bundle size view. */
-const RECOMMENDATIONS_RULE_ID = "performance/reduce-javascript-on-load";
-const RECOMMENDATION_CHANGES = [
-	"lazy-component",
-	"dynamic-import",
-	"narrower-import",
-	"replace",
-	"remove"
-];
-/** Changes that keep the code but load it later, so they need a trigger. */
-const DEFERRING_CHANGES = new Set(["lazy-component", "dynamic-import"]);
-const recommendationSchema = z.object({
-	pages: z.array(z.string()).min(1),
-	title: z.string().min(1).max(140),
-	change: z.enum(RECOMMENDATION_CHANGES),
-	target: z.string().min(1),
-	trigger: z.enum([
-		"interaction",
-		"visible",
-		"navigation",
-		"idle"
-	]).optional(),
-	how: z.string().min(1).max(1200),
-	files: z.array(z.object({
-		file: z.string(),
-		line: z.number().int().positive().optional()
-	}).strict()).min(1).max(10),
-	savings: z.array(z.object({
-		page: z.string(),
-		bytes: z.number().int().nonnegative(),
-		upTo: z.boolean()
-	}).strict()).optional()
-}).strict();
-const recommendationsSchema = z.array(recommendationSchema).max(30);
-const SEVERITY_ORDER = [
-	"critical",
-	"high",
-	"medium",
-	"low",
-	"info"
-];
-const evaluationSchema = z.object({
-	ruleId: z.string(),
-	disposition: z.enum([
-		"pass",
-		"finding",
-		"not-applicable",
-		"not-verified"
-	]),
-	title: z.string(),
-	description: z.string().optional(),
-	severity: z.enum(SEVERITY_ORDER).optional(),
-	summary: z.string(),
-	remediation: z.string().optional(),
-	evidence: z.array(evidenceSchema),
-	method: z.enum(["script", "ai"]).optional(),
-	waterfall: waterfallSchema.optional(),
-	recommendations: recommendationsSchema.optional()
-}).superRefine((value, context) => {
-	if (value.disposition === "finding" && value.evidence.length === 0) context.addIssue({
-		code: "custom",
-		message: "finding requires evidence",
-		path: ["evidence"]
-	});
-});
-const guidanceSchema = z.enum(GUIDANCE);
-const auditResultSchema = z.object({
-	schemaVersion: z.literal("1.0"),
-	run: z.object({
-		id: z.string(),
-		generatedAt: z.string(),
-		toolVersion: z.string()
-	}),
-	project: z.object({ name: z.string().optional() }),
-	pages: z.array(z.object({
-		label: z.string(),
-		url: z.string(),
-		playhouse: z.object({
-			archiveDir: z.string(),
-			version: z.string(),
-			lighthouseVersion: z.string(),
-			artifacts: z.record(z.string(), z.json())
-		})
-	})),
-	catalog: z.object({
-		categories: z.array(z.object({
-			id: z.string(),
-			title: z.string(),
-			ruleIds: z.array(z.string())
-		})),
-		ruleIds: z.array(z.string())
-	}),
-	evaluations: z.array(evaluationSchema),
-	observations: z.array(z.object({
-		title: z.string(),
-		category: z.string().optional(),
-		summary: z.string(),
-		evidence: z.array(evidenceSchema)
-	})).default([]),
-	coverage: z.array(z.object({
-		category: z.string().optional(),
-		ruleId: z.string().optional(),
-		page: z.string().optional(),
-		status: z.enum([
-			"covered",
-			"partial",
-			"missing"
-		]),
-		note: z.string()
-	})),
-	summary: z.object({
-		guidance: guidanceSchema,
-		narrative: z.string(),
-		highlights: z.array(z.string()).max(6).default([])
-	}).optional(),
-	bundle: bundleAnalysisSchema.optional()
-});
-function validateEvidence(evidence, archiveFiles) {
-	if (evidence.type === "source" && (evidence.file.split(/[\\/]/).includes("..") || pathIsAbsolute(evidence.file))) throw new Error(`Unsafe source evidence file: ${evidence.file}`);
-	if (evidence.type === "playhouse") {
-		const files = archiveFiles.get(evidence.page);
-		if (!files) throw new Error(`Unknown Playhouse evidence page: ${evidence.page}`);
-		if (!files.has(evidence.artifact)) throw new Error(`Unknown Playhouse evidence artifact for ${evidence.page}: ${evidence.artifact}`);
-	}
-}
-/** A waterfall belongs only to its rule, names captured pages once each, and is an acyclic graph of known steps. */
-function validateWaterfall(evaluation, pageLabels) {
-	if (!evaluation.waterfall) return;
-	if (evaluation.ruleId !== WATERFALL_RULE_ID) throw new Error(`waterfall is only supported on ${WATERFALL_RULE_ID}`);
-	const seenPages = /* @__PURE__ */ new Set();
-	for (const entry of evaluation.waterfall.pages) {
-		if (!pageLabels.has(entry.page)) throw new Error(`Unknown waterfall page: ${entry.page}`);
-		if (seenPages.has(entry.page)) throw new Error(`Duplicate waterfall page: ${entry.page}`);
-		seenPages.add(entry.page);
-		const steps = /* @__PURE__ */ new Map();
-		for (const step of entry.steps) {
-			if (steps.has(step.id)) throw new Error(`Duplicate waterfall step on ${entry.page}: ${step.id}`);
-			steps.set(step.id, step);
-			validateEvidence({
-				type: "source",
-				file: step.source.file
-			}, /* @__PURE__ */ new Map());
-		}
-		for (const step of entry.steps) {
-			for (const id of step.after) if (!steps.has(id)) throw new Error(`Waterfall step ${step.id} on ${entry.page} waits on unknown step: ${id}`);
-			if (step.opportunity === "stream" && (!step.blocking || step.critical)) throw new Error(`Waterfall step ${step.id} on ${entry.page} can only suggest streaming when it is awaited and not critical`);
-			if ((step.opportunity === "parallelize" || step.opportunity === "scapi-hook") && !step.after.length) throw new Error(`Waterfall step ${step.id} on ${entry.page} suggests ${step.opportunity} but waits on nothing`);
-		}
-		const done = /* @__PURE__ */ new Set();
-		const visiting = /* @__PURE__ */ new Set();
-		const visit = (id) => {
-			if (done.has(id)) return;
-			if (visiting.has(id)) throw new Error(`Waterfall on ${entry.page} has a cycle through step: ${id}`);
-			visiting.add(id);
-			for (const next of steps.get(id)?.after ?? []) visit(next);
-			visiting.delete(id);
-			done.add(id);
-		};
-		for (const id of steps.keys()) visit(id);
-	}
-}
-/**
-* Recommendations belong only to their rule, and each names a candidate or a package of every page it lists in the
-* bundle analysis, whose bytes it takes. Without `bundle` (re-validating a finished result) only the rule, pages and
-* files are checked.
-*/
-function validateRecommendations(evaluation, pageLabels, bundle) {
-	if (!evaluation.recommendations) return;
-	if (evaluation.ruleId !== RECOMMENDATIONS_RULE_ID) throw new Error(`recommendations is only supported on ${RECOMMENDATIONS_RULE_ID}`);
-	const seen = /* @__PURE__ */ new Set();
-	for (const item of evaluation.recommendations) {
-		const label = `${item.change} ${item.target}`;
-		if (seen.has(label)) throw new Error(`Duplicate recommendation: ${label}`);
-		seen.add(label);
-		if (new Set(item.pages).size !== item.pages.length) throw new Error(`Recommendation ${label} lists a page twice`);
-		for (const page of item.pages) if (!pageLabels.has(page)) throw new Error(`Unknown recommendation page: ${page}`);
-		for (const file of item.files) validateEvidence({
-			type: "source",
-			file: file.file
-		}, /* @__PURE__ */ new Map());
-		const deferring = DEFERRING_CHANGES.has(item.change);
-		if (deferring !== Boolean(item.trigger)) throw new Error(`Recommendation ${label} ${deferring ? "needs a trigger" : "only defers code with lazy-component or dynamic-import, so it takes no trigger"}`);
-		if (!bundle) continue;
-		item.savings = item.pages.map((page) => {
-			const local = bundle.pages.find((entry) => entry.page === page)?.local;
-			const candidate = local?.candidates.find((entry) => entry.target === item.target);
-			const owner = local?.packages.find((entry) => entry.name === item.target && entry.kind !== "build");
-			if (candidate) {
-				const file = item.files.find((entry) => entry.file === candidate.importer.file);
-				if (file && candidate.importer.line) file.line ??= candidate.importer.line;
-				return {
-					page,
-					bytes: candidate.savedBytes,
-					upTo: !deferring
-				};
-			}
-			if (owner) return deferring && owner.deferrableBytes !== void 0 ? {
-				page,
-				bytes: owner.deferrableBytes,
-				upTo: false
-			} : {
-				page,
-				bytes: owner.bytes,
-				upTo: true
-			};
-			throw new Error(`Recommendation ${label}: ${item.target} is not a candidate or package of ${page} in bundle/analysis.json`);
-		});
-		const most = Math.max(...item.savings.map((entry) => entry.bytes));
-		if (most < MIN_RECOMMENDED_BYTES) throw new Error(`Recommendation ${label} saves at most ${Math.round(most / 1024)} KiB on its pages, below the ${MIN_RECOMMENDED_BYTES / 1024} KiB worth recommending; leave it out`);
-	}
-}
-/** `archiveFiles` defaults to the artifacts embedded in `input.pages`. */
-function validateAuditResult(input, catalog, archiveFiles) {
-	const result = auditResultSchema.parse(input);
-	assertUniquePageLabels(result.pages);
-	if (!catalog && result.evaluations.some((evaluation) => evaluation.disposition === "finding" && !evaluation.severity)) throw new Error("finding requires severity");
-	const declaredRules = result.catalog.categories.flatMap((category) => category.ruleIds);
-	if (new Set(declaredRules).size !== declaredRules.length || declaredRules.slice().sort().join("\n") !== result.catalog.ruleIds.slice().sort().join("\n")) throw new Error("Catalog categories and ruleIds are inconsistent");
-	for (const category of result.catalog.categories) for (const ruleId of category.ruleIds) if (!ruleId.startsWith(`${category.id}/`)) throw new Error(`Catalog rule ${ruleId} is not in category ${category.id}`);
-	if (catalog) {
-		const known = new Set(catalog.ruleIds);
-		const categories = new Set(catalog.categories.map((category) => category.id));
-		const pages = archiveFiles ?? new Map(result.pages.map((page) => [page.label, new Set(Object.keys(page.playhouse.artifacts))]));
-		const severityByRule = new Map(catalog.categories.flatMap((category) => category.rules.map((rule) => [rule.id, rule.severity])));
-		const evaluated = /* @__PURE__ */ new Set();
-		for (const evaluation of result.evaluations) {
-			if (!known.has(evaluation.ruleId)) throw new Error(`Unknown rule id: ${evaluation.ruleId}`);
-			if (evaluated.has(evaluation.ruleId)) throw new Error(`Duplicate evaluation: ${evaluation.ruleId}`);
-			if (evaluation.disposition === "finding") {
-				const ceiling = severityByRule.get(evaluation.ruleId);
-				if (!ceiling) throw new Error(`Rule ${evaluation.ruleId} has no category in the catalog`);
-				const supplied = evaluation.severity;
-				evaluation.severity = supplied && SEVERITY_ORDER.indexOf(supplied) > SEVERITY_ORDER.indexOf(ceiling) ? supplied : ceiling;
-			}
-			evaluated.add(evaluation.ruleId);
-		}
-		for (const ruleId of catalog.ruleIds) if (!evaluated.has(ruleId)) result.evaluations.push({
-			ruleId,
-			disposition: "not-verified",
-			title: ruleId,
-			summary: "No evaluation was supplied.",
-			evidence: []
-		});
-		for (const evaluation of result.evaluations) for (const evidence of evaluation.evidence) validateEvidence(evidence, pages);
-		for (const observation of result.observations) for (const evidence of observation.evidence) validateEvidence(evidence, pages);
-		for (const item of result.coverage) {
-			if (item.ruleId && !known.has(item.ruleId)) throw new Error(`Unknown coverage rule id: ${item.ruleId}`);
-			if (item.category && !categories.has(item.category)) throw new Error(`Unknown coverage category: ${item.category}`);
-		}
-		result.summary = {
-			guidance: guidanceFor(result.evaluations),
-			narrative: result.summary?.narrative ?? "",
-			highlights: result.summary?.highlights ?? []
-		};
-		result.evaluations.sort((a, b) => a.ruleId.localeCompare(b.ruleId));
-		result.coverage.sort((a, b) => `${a.category ?? ""}/${a.ruleId ?? ""}/${a.page ?? ""}`.localeCompare(`${b.category ?? ""}/${b.ruleId ?? ""}/${b.page ?? ""}`));
-	}
-	const pageLabels = new Set(archiveFiles ? archiveFiles.keys() : result.pages.map((page) => page.label));
-	for (const evaluation of result.evaluations) {
-		validateWaterfall(evaluation, pageLabels);
-		validateRecommendations(evaluation, pageLabels);
-	}
-	for (const page of result.pages) {
-		page.url = sanitizeUrl(page.url);
-		page.playhouse.archiveDir = "[PLAYHOUSE_ARCHIVE]";
-		page.playhouse.artifacts = sanitizeJson(page.playhouse.artifacts);
-	}
-	for (const evaluation of result.evaluations) {
-		evaluation.title = sanitizeText(evaluation.title);
-		evaluation.summary = sanitizeText(evaluation.summary);
-		if (evaluation.remediation) evaluation.remediation = sanitizeText(evaluation.remediation);
-		for (const evidence of evaluation.evidence) sanitizeEvidence(evidence);
-		for (const entry of evaluation.waterfall?.pages ?? []) {
-			entry.route = sanitizeText(entry.route);
-			entry.summary = sanitizeText(entry.summary);
-			for (const step of entry.steps) {
-				step.label = sanitizeText(step.label);
-				if (step.conditional) step.conditional = sanitizeText(step.conditional);
-				if (step.note) step.note = sanitizeText(step.note);
-			}
-		}
-		for (const item of evaluation.recommendations ?? []) {
-			item.title = sanitizeText(item.title);
-			item.how = sanitizeText(item.how);
-		}
-	}
-	if (result.bundle) result.bundle = bundleAnalysisSchema.parse(sanitizeJson(result.bundle));
-	for (const observation of result.observations) {
-		observation.title = sanitizeText(observation.title);
-		observation.summary = sanitizeText(observation.summary);
-		for (const evidence of observation.evidence) sanitizeEvidence(evidence);
-	}
-	for (const item of result.coverage) item.note = sanitizeText(item.note);
-	if (result.summary) {
-		result.summary.narrative = sanitizeText(result.summary.narrative);
-		result.summary.highlights = result.summary.highlights.map(sanitizeText);
-	}
-	return result;
-}
-function assertUniquePageLabels(pages) {
-	const labels = /* @__PURE__ */ new Set();
-	for (const { label } of pages) {
-		if (!/^[a-z][a-z0-9-]{0,63}$/.test(label)) throw new Error(`Invalid page label: ${label}`);
-		if (labels.has(label)) throw new Error(`Duplicate page label: ${label}`);
-		labels.add(label);
-	}
-}
-function pathIsAbsolute(value) {
-	return value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value);
-}
-function sanitizeJson(value) {
-	return sanitizeJsonValue(value);
-}
-function sanitizeJsonPointer(pointer) {
-	if (!pointer.startsWith("/")) return sanitizeText(pointer);
-	return pointer.split("/").map((token, index) => index === 0 ? "" : sanitizeText(token)).join("/");
-}
-function sanitizeEvidence(evidence) {
-	if (evidence.type === "source" && evidence.excerpt) evidence.excerpt = sanitizeText(evidence.excerpt);
-	else if (evidence.type === "manual") {
-		evidence.description = sanitizeText(evidence.description);
-		if (evidence.location) evidence.location = sanitizeText(evidence.location);
-	} else if (evidence.type === "playhouse") {
-		if (evidence.pointer) evidence.pointer = sanitizeJsonPointer(evidence.pointer);
-		if (typeof evidence.value === "string") evidence.value = sanitizeText(evidence.value);
-	}
-}
-
-//#endregion
 //#region src/audit/events.ts
 const severity = z.enum([
 	"critical",
@@ -685,4 +177,4 @@ function endsRun(event) {
 }
 
 //#endregion
-export { runIdFor as S, validateWaterfall as _, progressEventSchema as a, listRuns as b, SEVERITY_ORDER as c, evidenceSchema as d, parsePrepared as f, validateRecommendations as g, validateEvidence as h, latestRunEvents as i, auditResultSchema as l, validateAuditResult as m, deriveStatus as n, readEvents as o, preparedSchema as p, endsRun as r, LIGHTHOUSE_REPORT as s, appendEvent as t, evaluationSchema as u, RUN_ID as v, runDir as x, latestRunDir as y };
+export { progressEventSchema as a, latestRunEvents as i, deriveStatus as n, readEvents as o, endsRun as r, appendEvent as t };

package/dist/flags2.js

@@ -1,15 +1,162 @@
 import { n as PROJECT_DIRECTORY_FLAG } from "./flags.js";
-import { n as sanitizeText } from "./sanitize.js";
+import { S as VERSION, _ as GUIDANCE, f as RUN_ID, n as SEVERITY_ORDER, y as sanitizeText } from "./results.js";
 import { Command, Errors, Flags } from "@oclif/core";
 import path from "node:path";
+import { readFile } from "node:fs/promises";
 
+//#region src/audit/telemetry.ts
+/**
+* The b2c CLI's Application Insights connection string: a public, write-only ingestion key that `@salesforce/b2c-cli`
+* already ships in its package.json, not a credential. It is the fallback for `pnpm exec sfnext audit`, where no host
+* CLI supplies one. It is deliberately not in this package's package.json: the SDK base classes of `push`, `scapi` and
+* the other commands read `oclif.telemetry` there and would start reporting too.
+*/
+const AUDIT_CONNECTION_STRING = "InstrumentationKey=6fcc215f-0b11-4864-ad5c-3945ae19e2f3;IngestionEndpoint=https://eastus-8.in.applicationinsights.azure.com/;LiveEndpoint=https://eastus.livediagnostics.monitor.azure.com/;ApplicationId=a60f17ec-265a-4dfc-b8df-03a64695697d";
+/** Events are sent every 30 s, so an audit that is killed mid-run loses at most that much. */
+const FLUSH_INTERVAL_MS = 3e4;
+/**
+* The event name prefix (`<project>/COMMAND_START`) and `origin`, fixed so the audit's events keep one name whether
+* they run under `pnpm exec sfnext` or a host CLI such as `b2c`, and never mix with the host CLI's own command events.
+* The running CLI goes in `hostCli`.
+*/
+const TELEMETRY_PROJECT = "@salesforce/storefront-next-dev";
+/**
+* Starts usage telemetry for an audit command, with the host CLI's connection string (the b2c CLI has one) or
+* {@link AUDIT_CONNECTION_STRING}. The B2C CLI's opt-outs apply (`SF_DISABLE_TELEMETRY`, `SFCC_DISABLE_TELEMETRY`).
+* Never throws.
+*/
+async function startAuditTelemetry(config, command) {
+	try {
+		const { Telemetry, createTelemetry } = await import("@salesforce/b2c-tooling-sdk/telemetry");
+		const pjson = config.pjson;
+		const appInsightsKey = Telemetry.getConnectionString(pjson.oclif?.telemetry?.connectionString ?? AUDIT_CONNECTION_STRING);
+		if (!appInsightsKey) return void 0;
+		const telemetry = createTelemetry({
+			project: TELEMETRY_PROJECT,
+			appInsightsKey,
+			version: config.version,
+			dataDir: config.dataDir,
+			flushIntervalMs: FLUSH_INTERVAL_MS,
+			initialAttributes: {
+				command,
+				surface: "sfnext-audit",
+				storefrontNextDevVersion: VERSION,
+				hostCli: config.name
+			}
+		});
+		await telemetry.start();
+		return telemetry;
+	} catch {
+		return;
+	}
+}
+const count = (value) => Array.isArray(value) ? value.length : 0;
+/** Strings come from files in the workspace, so only values of the expected shape are sent. */
+const runId = (value) => typeof value === "string" && RUN_ID.test(value) ? value : void 0;
+const guidance = (value) => typeof value === "string" && GUIDANCE.includes(value) ? value : void 0;
+const statusToken = (value) => typeof value === "string" && /^[a-z][a-z-]{0,23}$/.test(value) ? value : void 0;
+/**
+* The `command` dimension: the oclif id under the `sfnext` topic (`sfnext:audit:prepare`), the id the b2c CLI gives
+* these commands, so usage segments the same way whether `pnpm exec sfnext` or `b2c sfnext` ran them.
+*/
+const usageCommand = (id) => `sfnext:${(id ?? "").replace(/^sfnext:/, "")}`;
+/** An error's class name (`Error`, `CLIError`, `TypeError`), or `Error` when `name` holds anything else. */
+const errorName = (error) => typeof error.name === "string" && /^[A-Za-z_$][\w$]{0,63}$/.test(error.name) ? error.name : "Error";
+async function readJson(file) {
+	try {
+		return JSON.parse(await readFile(file, "utf8"));
+	} catch {
+		return;
+	}
+}
+/**
+* Counts from a run's prepared.json and bundle/analysis.json. Only counts, enums and the run id (a timestamp
+* that joins a run's prepare and finalize): never URLs, page labels, paths, rule text or findings.
+*/
+async function preparedAttributes(preparedPath, options) {
+	const [preparedFile, bundle] = await Promise.all([readJson(preparedPath), readJson(path.join(path.dirname(preparedPath), "bundle", "analysis.json"))]);
+	const prepared = preparedFile ?? {};
+	const run = prepared.run;
+	return {
+		auditRunId: runId(run?.id),
+		pagesCollected: count(prepared.pages),
+		pagesFailed: count(prepared.pageFailures),
+		pagesMissing: count(prepared.coverage),
+		rulesForAi: count(prepared.rules),
+		scriptFindings: count(prepared.decidedFindings),
+		runs: options.runs,
+		build: options.build,
+		bundleStatus: statusToken(bundle?.status)
+	};
+}
+/** Counts and the launch guidance from a run's audit-result.json, under the same rules as {@link preparedAttributes}. */
+async function finalizedAttributes(resultPath) {
+	const result = await readJson(resultPath) ?? {};
+	const run = result.run;
+	const summary = result.summary;
+	const evaluations = Array.isArray(result.evaluations) ? result.evaluations : [];
+	const findings = evaluations.filter((evaluation) => evaluation.disposition === "finding");
+	return {
+		auditRunId: runId(run?.id),
+		guidance: guidance(summary?.guidance),
+		pages: count(result.pages),
+		rules: evaluations.length,
+		rulesByScript: evaluations.filter((evaluation) => evaluation.method === "script").length,
+		rulesNotVerified: evaluations.filter((evaluation) => evaluation.disposition === "not-verified").length,
+		findings: findings.length,
+		...Object.fromEntries(SEVERITY_ORDER.map((severity) => [`findings${severity[0].toUpperCase()}${severity.slice(1)}`, findings.filter((finding) => finding.severity === severity).length]))
+	};
+}
+
+//#endregion
 //#region src/audit/command.ts
-/** Base for the audit commands: an error's message is sanitized before oclif prints it, so a token in a `--url` stays out of the terminal. */
+/**
+* Base for the audit commands: an error's message is sanitized before oclif prints it, so a token in a `--url` stays
+* out of the terminal. Each command also reports COMMAND_START, COMMAND_SUCCESS and COMMAND_ERROR
+* like the B2C CLI's own commands, but without the error message, which can hold a storefront URL.
+*/
 var AuditCommand = class extends Command {
+	/** Whether the command reports COMMAND_* events. Off for the ones an agent calls repeatedly or that keep running. */
+	static reportsUsage = true;
+	telemetry;
+	startedAt = Date.now();
+	async init() {
+		await super.init();
+		this.startedAt = Date.now();
+		if (!this.constructor.reportsUsage) return;
+		this.telemetry = await startAuditTelemetry(this.config, usageCommand(this.id));
+		this.telemetry?.sendEvent("COMMAND_START", { command: usageCommand(this.id) });
+		this.telemetry?.flush().catch(() => void 0);
+	}
+	/** Sends a usage event when telemetry is on. Building its attributes or sending it never fails the command. */
+	async track(event, attributes) {
+		if (!this.telemetry) return;
+		try {
+			this.telemetry.sendEvent(event, {
+				command: usageCommand(this.id),
+				...await attributes()
+			});
+		} catch {}
+	}
 	async catch(error) {
 		error.message = sanitizeText(error.message);
+		this.telemetry?.sendEvent("COMMAND_ERROR", {
+			command: usageCommand(this.id),
+			exitCode: error.oclif?.exit ?? error.exitCode ?? 1,
+			duration: Date.now() - this.startedAt,
+			errorName: errorName(error)
+		});
 		return super.catch(error);
 	}
+	async finally(error) {
+		if (!error) this.telemetry?.sendEvent("COMMAND_SUCCESS", {
+			command: usageCommand(this.id),
+			duration: Date.now() - this.startedAt
+		});
+		await this.telemetry?.stop().catch(() => void 0);
+		this.telemetry = void 0;
+		return super.finally(error);
+	}
 };
 
 //#endregion
@@ -31,4 +178,4 @@ function workspaceFor(flags) {
 }
 
 //#endregion
-export { AuditCommand as i, workspaceFlag as n, workspaceFor as r, text as t };
+export { finalizedAttributes as a, AuditCommand as i, workspaceFlag as n, preparedAttributes as o, workspaceFor as r, text as t };