statelyai 0.15.1 → 0.17.0

package/dist/coverageWorker.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/coverageWorker.mjs

@@ -0,0 +1,178 @@
+import { createRequire, registerHooks } from "node:module";
+import { readFile, realpath } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parentPort, workerData } from "node:worker_threads";
+import ts from "typescript";
+import { register } from "tsx/esm/api";
+import { createXStateSourceCoverageGraph, extractXStateSourceCoverage, getXStateSourceCoverageEventCases, instrumentXStateSourceCoverage } from "@statelyai/sdk/source-coverage";
+
+//#region src/sourceCoverageRunner.ts
+/** Executes trusted source with ordinary local permissions; called in a worker. */
+async function runSourceCoverageFile(options) {
+	const fileName = await realpath(resolve(options.sourceFile));
+	const source = await readFile(fileName, "utf8");
+	const manifest = await extractXStateSourceCoverage(source, { fileName });
+	if (!options.execute) return {
+		schemaVersion: 1,
+		mode: "extract",
+		status: manifest.complete ? "complete" : "incomplete",
+		manifest,
+		exitCode: manifest.complete ? 0 : 2
+	};
+	if (!manifest.complete) throw Object.assign(/* @__PURE__ */ new Error("Source extraction is incomplete."), { diagnostics: manifest.diagnostics });
+	const projectRequire = createRequire(fileName);
+	const load = async (name) => import(pathToFileURL(projectRequire.resolve(name)).href);
+	const graph = await load("@statelyai/graph");
+	const testing = await load("@xstate/test");
+	if (typeof graph.getSourceCoverageWitnesses !== "function" || typeof testing.createSourceCoverageSession !== "function") throw new Error("Source coverage requires @statelyai/graph with source-coverage planning and @xstate/test with createSourceCoverageSession. Upgrade these project dependencies.");
+	const runtimeName = options.runtime ?? "xstate";
+	const runtime = await load(runtimeName);
+	const runtimePackage = projectRequire(`${runtimeName}/package.json`);
+	const runtimeId = `${runtimePackage.name}@${runtimePackage.version}`;
+	if (typeof runtime.getMicrosteps !== "function") throw new Error("The selected runtime does not expose microstep execution.");
+	const instrumented = await instrumentXStateSourceCoverage(source, { fileName });
+	const transpiled = ts.transpileModule(instrumented.source, {
+		fileName,
+		compilerOptions: {
+			target: ts.ScriptTarget.ES2022,
+			module: ts.ModuleKind.ESNext
+		},
+		reportDiagnostics: true
+	});
+	if (transpiled.diagnostics?.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)) throw new Error("The instrumented module could not be compiled.");
+	const sourceUrl = pathToFileURL(fileName).href;
+	const unregister = register({ tsconfig: ts.findConfigFile(dirname(fileName), ts.sys.fileExists) ?? false });
+	const hooks = registerHooks({ load(url, context, nextLoad) {
+		if (url === sourceUrl) return {
+			format: "module",
+			source: transpiled.outputText,
+			shortCircuit: true
+		};
+		return nextLoad(url, context);
+	} });
+	try {
+		const module = await import(sourceUrl);
+		const selected = module[options.exportName ?? "machine"];
+		const control = module[instrumented.controlExport];
+		if (!selected || !control) throw new Error("Expected the selected machine export and source coverage control.");
+		const input = options.inputFile ? JSON.parse(await readFile(options.inputFile, "utf8")) : void 0;
+		const machineIndex = options.machineIndex ?? 0;
+		if (!Number.isSafeInteger(machineIndex) || machineIndex < 0 || machineIndex >= manifest.machineCount) throw new Error("machineIndex is outside the extracted machine range.");
+		const selectedManifest = {
+			...manifest,
+			obligations: manifest.obligations.filter((obligation) => obligation.machineIndex === machineIndex)
+		};
+		const createSession = (input) => {
+			const machine = typeof selected === "function" ? selected(input) : selected;
+			if (!machine.eventSchema || !machine.sources) throw new Error("Source coverage execution currently requires an XState v6 machine.");
+			return testing.createSourceCoverageSession(machine, control, {
+				input,
+				runtimeId,
+				validateEvent: async (event, snapshot) => {
+					const candidate = event;
+					if (typeof candidate.type === "string" && candidate.type.startsWith("xstate.") && typeof runtime.getNextTransitions === "function" && runtime.getNextTransitions(snapshot).some((transition) => transition.eventType === candidate.type && Object.entries(transition.matches ?? {}).every(([key, value]) => Object.is(candidate[key], value)))) return;
+					const validation = await machine.eventSchema["~standard"].validate(event);
+					if (validation.issues) throw new Error(`Event validation failed: ${JSON.stringify(validation.issues)}`);
+				}
+			});
+		};
+		let result;
+		if (options.replayFile) {
+			const saved = JSON.parse(await readFile(options.replayFile, "utf8"));
+			const witnesses = Array.isArray(saved) ? saved : saved.witnesses;
+			if (!Array.isArray(witnesses)) throw new Error("Replay file must contain a witness array or a report with witnesses.");
+			const actual = [];
+			for (const witness of witnesses) actual.push((await graph.getSourceCoverageReplay(manifest, witness, createSession)).witness);
+			result = {
+				report: graph.getSourceCoverageReport(selectedManifest, actual),
+				witnesses: actual,
+				exploration: { replayed: actual.length }
+			};
+		} else {
+			if (!options.casesFile) throw new Error("Execution requires --cases or --replay.");
+			const cases = JSON.parse(await readFile(options.casesFile, "utf8"));
+			if (!Array.isArray(cases) || cases.some((event) => !event || typeof event.type !== "string")) throw new Error("Cases must be an array of event objects with string types.");
+			const suggest = options.suggestFile ? (await import(pathToFileURL(resolve(options.suggestFile)).href)).default : void 0;
+			if (options.suggestFile && typeof suggest !== "function") throw new Error("Suggestion module must default-export a function.");
+			result = await graph.getSourceCoverageWitnesses({
+				manifest,
+				machineIndex,
+				input,
+				createSession,
+				events: cases,
+				maxStates: options.maxStates,
+				maxDepth: options.maxDepth,
+				maxExecutions: options.maxExecutions,
+				suggestEvents: async (args) => {
+					const boundaries = getXStateSourceCoverageEventCases({
+						...selectedManifest,
+						obligations: args.uncovered
+					}, args.state.snapshot, cases);
+					const suggestions = await suggest?.({
+						...args,
+						sourceHash: manifest.source.hash
+					}) ?? [];
+					if (!Array.isArray(suggestions) || suggestions.some((event) => !event || typeof event.type !== "string")) throw new Error("Suggested cases must be event objects.");
+					return [...boundaries, ...suggestions];
+				}
+			});
+			if (options.shrink !== false) {
+				const minimized = [];
+				for (const witness of result.witnesses) minimized.push((await graph.getMinimizedSourceCoverageWitness(manifest, witness, createSession, { maxExecutions: 100 })).witness);
+				result.witnesses = graph.getReducedSourceCoverageWitnesses(selectedManifest, minimized);
+			}
+			const verified = [];
+			for (const witness of result.witnesses) verified.push((await graph.getSourceCoverageReplay(manifest, witness, createSession)).witness);
+			result.witnesses = verified;
+			result.report = graph.getSourceCoverageReport(selectedManifest, verified);
+		}
+		const projection = await createXStateSourceCoverageGraph(source, result.report, {
+			fileName,
+			machineIndex,
+			profile: "xstate-v6-alpha"
+		});
+		const machine = typeof selected === "function" ? selected(input) : selected;
+		const schemas = Object.entries(machine.schemas?.events ?? {});
+		const typeOnlyEvents = schemas.filter(([, schema]) => schema?.["~standard"]?.vendor === "xstate.types").map(([type]) => type);
+		const runtimeSchemaEvents = schemas.filter(([, schema]) => schema?.["~standard"]?.vendor && schema["~standard"].vendor !== "xstate.types").map(([type]) => type);
+		const unconstrainedEvents = [...new Set(result.witnesses.flatMap((witness) => witness.events.map((event) => event.type)))].filter((type) => !schemas.some(([key]) => key === type));
+		return {
+			schemaVersion: 1,
+			mode: options.replayFile ? "replay" : "execute",
+			status: result.report.complete ? "complete" : "incomplete",
+			machineIndex,
+			runtimeId,
+			effectsExecuted: false,
+			payloadValidation: {
+				typeOnlyEvents,
+				runtimeSchemaEvents,
+				unconstrainedEvents,
+				modeledRuntimeEvents: result.witnesses.flatMap((witness) => witness.events.filter((event) => event.type.startsWith("xstate.")))
+			},
+			manifest: selectedManifest,
+			...result,
+			graph: projection.graph,
+			exitCode: result.report.complete ? 0 : 1
+		};
+	} finally {
+		hooks.deregister();
+		await unregister();
+	}
+}
+
+//#endregion
+//#region src/coverageWorker.ts
+if (parentPort) runSourceCoverageFile(workerData).then((result) => parentPort.postMessage({
+	ok: true,
+	result
+}), (error) => parentPort.postMessage({
+	ok: false,
+	error: {
+		message: error instanceof Error ? error.message : String(error),
+		diagnostics: error?.diagnostics
+	}
+}));
+
+//#endregion
+export {  };

package/dist/index.d.mts

@@ -69,10 +69,10 @@ declare const behaviorCiResultsSchema: z.ZodArray<z.ZodObject<{
   file: z.ZodString;
   fullName: z.ZodString;
   outcome: z.ZodEnum<{
-    error: "error";
     passed: "passed";
     failed: "failed";
     skipped: "skipped";
+    error: "error";
   }>;
   detail: z.ZodString;
 }, z.core.$strict>>;
@@ -129,6 +129,53 @@ declare class BehaviorCalibrateCommand extends Command {
   run(): Promise<void>;
 }
 //#endregion
+//#region src/sourceCoverageRunner.d.ts
+interface SourceCoverageRunOptions {
+  sourceFile: string;
+  execute?: boolean;
+  casesFile?: string;
+  inputFile?: string;
+  replayFile?: string;
+  runtime?: string;
+  exportName?: string;
+  machineIndex?: number;
+  maxStates?: number;
+  maxDepth?: number;
+  maxExecutions?: number;
+  shrink?: boolean;
+  /** Trusted callback module supplying additional event cases from coverage gaps. */
+  suggestFile?: string;
+}
+//#endregion
+//#region src/sourceCoverageCommand.d.ts
+declare function runSourceCoverageWorker(options: SourceCoverageRunOptions, timeoutMs?: number, workerUrl?: URL): Promise<any>;
+declare class SourceCoverageCommand extends Command {
+  static enableJsonFlag: boolean;
+  static summary: string;
+  static description: string;
+  static args: {
+    source: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+  };
+  static flags: {
+    execute: _oclif_core_interfaces0.BooleanFlag<boolean>;
+    cases: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    input: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    replay: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    runtime: _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
+    export: _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
+    "machine-index": _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
+    "max-states": _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
+    "max-depth": _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
+    "max-executions": _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
+    timeout: _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
+    shrink: _oclif_core_interfaces0.BooleanFlag<boolean>;
+    suggest: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    report: _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
+    graph: _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+  };
+  run(): Promise<void>;
+}
+//#endregion
 //#region src/testCommand.d.ts
 declare class TestCommand extends Command {
   static enableJsonFlag: boolean;
@@ -321,7 +368,7 @@ declare function createStatelyProjectConfig(options: {
   defaultXStateVersion?: number;
 }): StatelyProjectConfig;
 //#endregion
-//#region ../../node_modules/.pnpm/@statelyai+graph@2.1.0_@statelyai+layout@0.4.3_cytoscape@3.34.0_d3-force@3.0.0_d3-hiera_2afdfa88fae2fa10712f99651d0f58d6/node_modules/@statelyai/graph/dist/types-BAEQTwK_.d.mts
+//#region ../../node_modules/.pnpm/@statelyai+graph@2.1.0_@statelyai+layout@0.5.0_cytoscape@3.34.0_d3-force@3.0.0_d3-hiera_b5a11f1847a44c5e54d10b16dab0c7b9/node_modules/@statelyai/graph/dist/types-BAEQTwK_.d.mts
 //#region src/types.d.ts
 /**
  * Directedness of a graph or an individual edge.
@@ -885,6 +932,7 @@ declare const COMMANDS: {
   'behavior:check': typeof BehaviorCheckCommand;
   'behavior:adopt': typeof BehaviorAdoptCommand;
   test: typeof TestCommand;
+  coverage: typeof SourceCoverageCommand;
   verify: typeof VerifyCommand;
   plan: typeof PlanCommand;
   diff: typeof DiffCommand;
@@ -910,8 +958,8 @@ declare const verificationRunReportSchema: z.ZodObject<{
   version: z.ZodLiteral<1>;
   suite: z.ZodString;
   status: z.ZodEnum<{
-    failed: "failed";
     passed: "passed";
+    failed: "failed";
   }>;
   verdict: z.ZodEnum<{
     inconclusive: "inconclusive";
@@ -1016,8 +1064,8 @@ declare const verificationRunReportSchema: z.ZodObject<{
     type: z.ZodLiteral<"path-result">;
     id: z.ZodString;
     status: z.ZodEnum<{
-      failed: "failed";
       passed: "passed";
+      failed: "failed";
     }>;
     witnessedStates: z.ZodArray<z.ZodString>;
     witnessedTransitions: z.ZodArray<z.ZodString>;
@@ -1028,8 +1076,8 @@ declare const verificationRunReportSchema: z.ZodObject<{
     state: z.ZodString;
     event: z.ZodString;
     status: z.ZodEnum<{
-      failed: "failed";
       passed: "passed";
+      failed: "failed";
     }>;
   }, z.core.$strip>>>;
   divergences: z.ZodArray<z.ZodObject<{
@@ -1073,8 +1121,8 @@ declare const verificationRunReportSchema: z.ZodObject<{
       predicateResults: z.ZodArray<z.ZodObject<{
         state: z.ZodString;
         status: z.ZodEnum<{
-          failed: "failed";
           passed: "passed";
+          failed: "failed";
         }>;
         signals: z.ZodArray<z.ZodString>;
         message: z.ZodOptional<z.ZodString>;
@@ -1088,8 +1136,8 @@ declare const verificationRunReportSchema: z.ZodObject<{
       predicateResults: z.ZodArray<z.ZodObject<{
         state: z.ZodString;
         status: z.ZodEnum<{
-          failed: "failed";
           passed: "passed";
+          failed: "failed";
         }>;
         signals: z.ZodArray<z.ZodString>;
         message: z.ZodOptional<z.ZodString>;
@@ -1159,8 +1207,8 @@ declare const verificationRunReportSchema: z.ZodObject<{
         predicateResults: z.ZodArray<z.ZodObject<{
           state: z.ZodString;
           status: z.ZodEnum<{
-            failed: "failed";
             passed: "passed";
+            failed: "failed";
           }>;
           signals: z.ZodArray<z.ZodString>;
           message: z.ZodOptional<z.ZodString>;
@@ -1174,8 +1222,8 @@ declare const verificationRunReportSchema: z.ZodObject<{
         predicateResults: z.ZodArray<z.ZodObject<{
           state: z.ZodString;
           status: z.ZodEnum<{
-            failed: "failed";
             passed: "passed";
+            failed: "failed";
           }>;
           signals: z.ZodArray<z.ZodString>;
           message: z.ZodOptional<z.ZodString>;
@@ -1229,8 +1277,8 @@ declare const verificationRequestSchema: z.ZodObject<{
       version: z.ZodLiteral<1>;
       suite: z.ZodString;
       status: z.ZodEnum<{
-        failed: "failed";
         passed: "passed";
+        failed: "failed";
       }>;
       verdict: z.ZodEnum<{
         inconclusive: "inconclusive";
@@ -1335,8 +1383,8 @@ declare const verificationRequestSchema: z.ZodObject<{
         type: z.ZodLiteral<"path-result">;
         id: z.ZodString;
         status: z.ZodEnum<{
-          failed: "failed";
           passed: "passed";
+          failed: "failed";
         }>;
         witnessedStates: z.ZodArray<z.ZodString>;
         witnessedTransitions: z.ZodArray<z.ZodString>;
@@ -1347,8 +1395,8 @@ declare const verificationRequestSchema: z.ZodObject<{
         state: z.ZodString;
         event: z.ZodString;
         status: z.ZodEnum<{
-          failed: "failed";
           passed: "passed";
+          failed: "failed";
         }>;
       }, z.core.$strip>>>;
       divergences: z.ZodArray<z.ZodObject<{
@@ -1392,8 +1440,8 @@ declare const verificationRequestSchema: z.ZodObject<{
           predicateResults: z.ZodArray<z.ZodObject<{
             state: z.ZodString;
             status: z.ZodEnum<{
-              failed: "failed";
               passed: "passed";
+              failed: "failed";
             }>;
             signals: z.ZodArray<z.ZodString>;
             message: z.ZodOptional<z.ZodString>;
@@ -1407,8 +1455,8 @@ declare const verificationRequestSchema: z.ZodObject<{
           predicateResults: z.ZodArray<z.ZodObject<{
             state: z.ZodString;
             status: z.ZodEnum<{
-              failed: "failed";
               passed: "passed";
+              failed: "failed";
             }>;
             signals: z.ZodArray<z.ZodString>;
             message: z.ZodOptional<z.ZodString>;
@@ -1478,8 +1526,8 @@ declare const verificationRequestSchema: z.ZodObject<{
             predicateResults: z.ZodArray<z.ZodObject<{
               state: z.ZodString;
               status: z.ZodEnum<{
-                failed: "failed";
                 passed: "passed";
+                failed: "failed";
               }>;
               signals: z.ZodArray<z.ZodString>;
               message: z.ZodOptional<z.ZodString>;
@@ -1493,8 +1541,8 @@ declare const verificationRequestSchema: z.ZodObject<{
             predicateResults: z.ZodArray<z.ZodObject<{
               state: z.ZodString;
               status: z.ZodEnum<{
-                failed: "failed";
                 passed: "passed";
+                failed: "failed";
               }>;
               signals: z.ZodArray<z.ZodString>;
               message: z.ZodOptional<z.ZodString>;
@@ -1822,4 +1870,4 @@ declare function verifyProject(options?: VerifyProjectOptions): Promise<{
 /** One case per recorded path/probe. Unattributed divergences remain separate cases. */
 declare function formatVerificationJUnit(report: VerificationRunReport): string;
 //#endregion
-export { ApiKeyResolution, type BehaviorCiAdapter, type BehaviorCiConfig, type BehaviorCiResult, COMMANDS, CredentialStatus, DiscoveredMachine, InitProjectOptions, InitProjectResult, type LinkProjectOptions, LinkedPullTarget, OAuthLoginDiscovery, ProjectMachineStatus, ProjectStatusMachine, ProjectStatusResult, PushCandidateClassification, RemoteProjectMachineTarget, ResolveApiKeyOptions, ResolvedConfiguredPullTargets, ScanProjectSourcesOptions, type VerificationExecutor, type VerificationRequest, type VerificationRunReport, type VerifyProjectOptions, adoptBehavior, behaviorCiConfigSchema, behaviorCiResultsSchema, briefReport, buildOAuthLoginStart, calibrateBehavior, changesReport, checkBehavior, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverMachinesInSource, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatDiscoveredMachines, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, formatVerificationJUnit, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, linkProject, pendingReport, readGraphFile, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveOpenRootDir, resolveProjectStatus, resolveVerificationRequest, resourceId, run, scanProjectMachines, scanProjectSources, verifyProject, verifyReport };
+export { ApiKeyResolution, type BehaviorCiAdapter, type BehaviorCiConfig, type BehaviorCiResult, COMMANDS, CredentialStatus, DiscoveredMachine, InitProjectOptions, InitProjectResult, type LinkProjectOptions, LinkedPullTarget, OAuthLoginDiscovery, ProjectMachineStatus, ProjectStatusMachine, ProjectStatusResult, PushCandidateClassification, RemoteProjectMachineTarget, ResolveApiKeyOptions, ResolvedConfiguredPullTargets, ScanProjectSourcesOptions, SourceCoverageCommand, type SourceCoverageRunOptions, type VerificationExecutor, type VerificationRequest, type VerificationRunReport, type VerifyProjectOptions, adoptBehavior, behaviorCiConfigSchema, behaviorCiResultsSchema, briefReport, buildOAuthLoginStart, calibrateBehavior, changesReport, checkBehavior, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverMachinesInSource, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatDiscoveredMachines, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, formatVerificationJUnit, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, linkProject, pendingReport, readGraphFile, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveOpenRootDir, resolveProjectStatus, resolveVerificationRequest, resourceId, run, runSourceCoverageWorker, scanProjectMachines, scanProjectSources, verifyProject, verifyReport };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { A as formatVerificationJUnit, B as calibrateBehavior, C as run, D as resourceId, E as linkProject, F as readGraphFile, I as verifyReport, L as adoptBehavior, M as briefReport, N as changesReport, O as resolveVerificationRequest, P as pendingReport, R as behaviorCiConfigSchema, S as resolveProjectStatus, T as scanProjectSources, V as checkBehavior, _ as isFileGitDirty, a as discoverMachinesInSource, b as resolveCredentialStatus, c as formatDiscoveredMachines, d as formatProjectStatus, f as formatStoredCredentialSource, g as initProject, h as inferInitProjectName, i as discoverLinkedPullTargets, j as createStatelyProjectConfig, k as verifyProject, l as formatMissingNewMachineDirMessage, m as getEnvCredential, n as buildOAuthLoginStart, o as discoverOAuthLogin, p as getEnvApiKey, r as classifyPushCandidates, s as discoverRemoteProjectMachineTargets, t as COMMANDS, u as formatPlanSummary, v as resolveApiKey, w as scanProjectMachines, x as resolveOpenRootDir, y as resolveConfiguredPullTargets, z as behaviorCiResultsSchema } from "./cli-CE7KhcOJ.mjs";
+import { A as formatVerificationJUnit, B as behaviorCiConfigSchema, C as run, D as resourceId, E as linkProject, F as readGraphFile, H as calibrateBehavior, I as verifyReport, L as SourceCoverageCommand, M as briefReport, N as changesReport, O as resolveVerificationRequest, P as pendingReport, R as runSourceCoverageWorker, S as resolveProjectStatus, T as scanProjectSources, U as checkBehavior, V as behaviorCiResultsSchema, _ as isFileGitDirty, a as discoverMachinesInSource, b as resolveCredentialStatus, c as formatDiscoveredMachines, d as formatProjectStatus, f as formatStoredCredentialSource, g as initProject, h as inferInitProjectName, i as discoverLinkedPullTargets, j as createStatelyProjectConfig, k as verifyProject, l as formatMissingNewMachineDirMessage, m as getEnvCredential, n as buildOAuthLoginStart, o as discoverOAuthLogin, p as getEnvApiKey, r as classifyPushCandidates, s as discoverRemoteProjectMachineTargets, t as COMMANDS, u as formatPlanSummary, v as resolveApiKey, w as scanProjectMachines, x as resolveOpenRootDir, y as resolveConfiguredPullTargets, z as adoptBehavior } from "./cli-BBG--n3O.mjs";
 
-export { COMMANDS, adoptBehavior, behaviorCiConfigSchema, behaviorCiResultsSchema, briefReport, buildOAuthLoginStart, calibrateBehavior, changesReport, checkBehavior, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverMachinesInSource, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatDiscoveredMachines, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, formatVerificationJUnit, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, linkProject, pendingReport, readGraphFile, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveOpenRootDir, resolveProjectStatus, resolveVerificationRequest, resourceId, run, scanProjectMachines, scanProjectSources, verifyProject, verifyReport };
+export { COMMANDS, SourceCoverageCommand, adoptBehavior, behaviorCiConfigSchema, behaviorCiResultsSchema, briefReport, buildOAuthLoginStart, calibrateBehavior, changesReport, checkBehavior, classifyPushCandidates, createStatelyProjectConfig, discoverLinkedPullTargets, discoverMachinesInSource, discoverOAuthLogin, discoverRemoteProjectMachineTargets, formatDiscoveredMachines, formatMissingNewMachineDirMessage, formatPlanSummary, formatProjectStatus, formatStoredCredentialSource, formatVerificationJUnit, getEnvApiKey, getEnvCredential, inferInitProjectName, initProject, isFileGitDirty, linkProject, pendingReport, readGraphFile, resolveApiKey, resolveConfiguredPullTargets, resolveCredentialStatus, resolveOpenRootDir, resolveProjectStatus, resolveVerificationRequest, resourceId, run, runSourceCoverageWorker, scanProjectMachines, scanProjectSources, verifyProject, verifyReport };

package/dist/skills/setup-behavior-ci/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: setup-behavior-ci
+description: Set up deterministic Stately behavior CI from existing Vitest tests or authored executable model-based campaigns, with reviewed requirements, calibrated mappings, real application adapters and immutable evidence history.
+---
+
+Set up the selected feature from real source and authoritative intent. CI runs the existing CLI and tests without an LLM. Author the model and bindings for the user; do not ask them to maintain hashes.
+
+Choose the mode before setup. Preserve the existing selected-Vitest mode when connecting current tests to an estimated model. For an executable model-based campaign, read [executable mode](references/executable.md), author the model, generators, real adapter and requirement assertions, then apply the shared calibration/adoption rules below. Do not treat estimated graph coverage as executed requirement evidence.
+
+This skill ships with `statelyai` at `dist/skills/setup-behavior-ci/SKILL.md`. Resolve its exported `statelyai/skills/setup-behavior-ci/SKILL.md` path from a local install; copy the complete skill directory into the target agent's skill location when installation is requested. Its relative assets/references remain usable outside this monorepo. Repository `.agents/skills/setup-behavior-ci` is the sole maintained source; the package build copies it deterministically.
+
+For selected-Vitest mode:
+
+1. Discover the feature's existing test files, native runner command/configuration, source dependencies and authoritative requirements. Run the actual bounded Vitest selection once with `--reporter=json --outputFile=<fresh temporary file>`. Read native `testResults[].name` and `assertionResults[].fullName`; copy exact titles into mappings. Map every case in the selected native command, including existing public tests. Compare the complete `(file, fullName)` inventory against config mappings and require exact equality before proceeding. Label ancillary observed smoke checks as observations rather than invented requirements. Preserve existing behavioral assertions. Don't substitute toy tests or invent reporter titles.
+2. Read [the contract](references/contract.md). Generate a short `spec.json` with meaningful stable requirement/check IDs, acceptance criteria, source authority/citations, and `retire: []`. Requirements inferred from implementation must be labeled inference. Estimate the behavior as XGraph JSON in `model.json`; describe states/transitions that matter, including retained edge cases. Entity mappings aid investigation; they do not prove coverage. Review generated meaning against source/spec and existing assertions. The model is an estimate, not executable test truth.
+3. Independently challenge the estimated model with external inputs. Inventory all seven categories in [plan](assets/plan.json): user, host-update, async-result, cancellation, timer, server-event, lifecycle. Trace each relevant state owner and ingress in source, not just the selected tests. Combine operations across owners, such as host replacement after selection, cancellation before completion, disposal during work, and timer expiry during retry. Map discovered obligations to stable requirement/check/entity IDs, or record a cited gap or reasoned not-applicable entry. Keep cited intent, observations, inferences and assumptions distinct. Existing passing tests do not settle requirement conflicts.
+4. Copy/adapt [config](assets/config.json) and the self-contained [Vitest adapter](assets/vitest-adapter.mjs). Select bounded source, test producer, runner configuration, and meaningful dependency files. Paths are repository-relative, including check file paths; command cwd may be a package. Include project/package manifests and lockfiles for the selected dependency scope. The CLI automatically includes root and command-cwd manifests/locks, config/spec/model/adapter/mapped tests and exact baseline files. Materialize external/user intent in checked requirements documents and list authoritative intent files in `plan.authorityInputs`; edits to them must invalidate calibration. Put runner/producer configuration modules in `plan.runnerInputs` so changes require recalibration. Pin CI Node and package-manager versions to the calibrated versions; original and current OS/architecture remain evidence. Limit all selected files together to 200. No broad workspace directory or `node_modules` selection. Keep state/output outside inputs.
+5. Adapt [workflow](assets/workflow.yml) to the repository's package manager, lockfile, installation, CLI pin/build, selected command and paths. Use hosted runners by default, `contents: read`, unconditional artifact upload including hidden files and job summary. Keep `GITHUB_SHA` tied to actual checkout. Never run an LLM, auto-adopt, push, or add auth credentials in CI. Include the actual workflow path and Vitest config in config inputs before staging and checking. Existing trusted self-hosted runner workflows require same-repository trusted branch triggers, not arbitrary fork code.
+6. Stage generated input files with `git add` before the first local run. `baseline: null` bootstraps a public FileStore model and behavior record. Run `statelyai behavior calibrate --config <config> --output <fresh ignored directory>` against the unchanged implementation first. The CLI executes the real native runner and generates a self-contained calibration receipt. Inspect every mismatch against authoritative requirements. Correct a wrong model/test assumption or fix the implementation, then recalibrate. If a known implementation defect must remain red, add a cited, reasoned `implementation-defect` disposition to the plan before recalibration. Unresolved calibration mismatches block adoption. Never copy observed bugs into the requirements automatically. Inspect summary, native report, argv/exit/logs, manifest, model bindings and current gaps. A passing run is exit 0; mapped test failures/missing/skipped checks are 1; invalid evidence is 2. Fix setup errors; do not shrink obligations to make red pass.
+7. Explicitly run `statelyai behavior adopt <inspected output> --config <config>`. Adopt red as well as green records before the next evolution so failures remain in history. Commit generated config/spec/model/adapter/plan, the installed calibration receipt and the complete stateRoot `.statelyai` tree. Adoption updates baseline; no manual hashes. For dirty local runs, bound bytes must still match when adopting. `git add -f` may be needed when repository ignores `.statelyai`. Never commit output logs/runstore.
+8. Verify the generated setup with the built/installed CLI and real tests. Check a deliberate assertion failure in a selected existing test produces exit 1, a missing required mapping cannot pass, and a restored run passes while history still shows failure. Any unmapped selected case, including a passing case, is ERROR and cannot be adopted; fix the mapping inventory before application repair. Never turn that ERROR into a claimed behavioral FAIL. Keep experimental changes isolated. Remote execution is a separate verification step requiring actual run/log/artifact evidence. On a remote red or green run, download and inspect the artifact, adopt it against its exact checked parent, then commit the advanced state before the next run.
+
+Normal CI runs `behavior check` with the checked receipt. Changed model/spec/plan/mappings/adapter/producer or runner identity requires explicit native recalibration and inspected adoption. Implementation changes run against the stable calibrated contract. Calibration binds its original revision and files; it does not pin all future app revisions. Schema 1 remains readable but has no setup assurance claim.
+
+On later requirement changes, update spec and model estimate, preserve IDs for the same obligation, and use an explicit reasoned retirement to remove one. Omitted requirements/checks remain active. Refresh mappings from actual reporter output when tests change. Adopt refuses divergent ancestry; inspect both refs and rerun from the chosen checked baseline rather than rewriting artifact history.

package/dist/skills/setup-behavior-ci/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: 'Setup Behavior CI'
+  short_description: 'Set up Vitest or executable campaign behavior CI'

package/dist/skills/setup-behavior-ci/assets/campaign-adapter.mjs

@@ -0,0 +1,203 @@
+const statuses = new Set(["passed", "discrepancy", "inconclusive"]);
+const nonempty = (value) => typeof value === "string" && value.trim().length > 0;
+const count = (value) => Number.isSafeInteger(value) && value >= 0;
+const fail = (message) => {
+  throw new Error(`Invalid campaign evidence: ${message}`);
+};
+
+export const executionFullName = "campaign.execution";
+export const assertionFullName = (requirementId, checkId) =>
+  `campaign.assertion ${JSON.stringify([requirementId, checkId])}`;
+
+export default function normalize(envelope) {
+  const { file, report } = envelope ?? {};
+  if (
+    !nonempty(file) ||
+    file.startsWith("/") ||
+    file.includes("\\") ||
+    file.split("/").some((part) => !part || part === "." || part === "..") ||
+    !file.endsWith(".mjs")
+  )
+    fail("file must be a repository-relative campaign .mjs path");
+  if (report?.formatVersion !== 1 || report.mode !== "campaign" || !statuses.has(report.status))
+    fail("expected a native full-campaign report");
+  if (
+    !Array.isArray(report.phases) ||
+    report.phases.length !== 2 ||
+    report.phases[0]?.phase !== "paths" ||
+    report.phases[1]?.phase !== "property" ||
+    report.phases.some((phase) => !statuses.has(phase.status))
+  )
+    fail("expected paths and property phases in order");
+  const status = report.phases.some((phase) => phase.status === "inconclusive")
+    ? "inconclusive"
+    : report.phases.some((phase) => phase.status === "discrepancy")
+      ? "discrepancy"
+      : "passed";
+  if (status !== report.status) fail("native verdict conflicts with phases");
+
+  if (
+    !nonempty(report.campaign?.id) ||
+    !nonempty(report.campaign.intent) ||
+    !nonempty(report.campaign.scope) ||
+    !nonempty(report.campaign.modelVersion) ||
+    !Array.isArray(report.campaign.assumptions) ||
+    !report.campaign.assumptions.every(nonempty) ||
+    !Array.isArray(report.campaign.evidence) ||
+    !report.campaign.evidence.every(nonempty) ||
+    !/^[a-f0-9]{64}$/.test(report.provenance?.entrySha256 ?? "") ||
+    report.provenance?.hashScope !== "entry-module-only" ||
+    !nonempty(report.provenance.node) ||
+    !["runner", "xstate", "xstateTest", "fastCheck"].every((key) =>
+      nonempty(report.provenance.versions?.[key]),
+    ) ||
+    !Number.isSafeInteger(report.budget?.seed) ||
+    !["numRuns", "maxCommands", "pathLimit", "timeoutMs"].every(
+      (key) => count(report.budget?.[key]) && report.budget[key] > 0,
+    )
+  )
+    fail("native campaign metadata, provenance or budget missing");
+  for (const phase of report.phases) {
+    if (phase.status !== "passed" && !nonempty(phase.message)) fail("native diagnostic missing");
+    if (phase.status !== "passed" && phase.requirementGaps === undefined) continue;
+    const coverage = phase.coverage;
+    if (
+      !coverage ||
+      !count(coverage.totals?.runs) ||
+      coverage.totals.runs === 0 ||
+      !coverage.exploration ||
+      typeof coverage.exploration.truncated !== "boolean" ||
+      !Array.isArray(coverage.exploration.truncationReasons) ||
+      (coverage.exploration.truncated &&
+        (coverage.exploration.truncationReasons.length === 0 ||
+          coverage.exploration.truncationReasons.some(
+            (reason) => phase.phase !== "property" || reason !== "maximum sequence length reached",
+          ))) ||
+      !Array.isArray(coverage.temporal?.failed) ||
+      coverage.temporal.failed.length > 0 ||
+      !Array.isArray(coverage.temporal?.inconclusive) ||
+      coverage.temporal.inconclusive.length > 0
+    )
+      fail("passing or coverage-gap native phase lacks completed execution evidence");
+    const assertions = [
+      "sutComparisons",
+      "oracleComparisons",
+      "invariantChecks",
+      "temporalChecks",
+    ].map((key) => coverage.totals[key]);
+    assertions.push(phase.additionalAssertions ?? 0);
+    if (!assertions.every(count) || assertions.reduce((total, value) => total + value, 0) === 0)
+      fail("passing or coverage-gap native phase lacks observable assertions");
+  }
+
+  const declarations = report.campaign?.requirements;
+  if (!Array.isArray(declarations) || declarations.length === 0)
+    fail("nonempty campaign.requirements declarations required");
+  const requirements = new Map();
+  const checks = new Set();
+  for (const requirement of declarations) {
+    if (
+      !nonempty(requirement?.id) ||
+      requirements.has(requirement.id) ||
+      !Array.isArray(requirement.checks) ||
+      requirement.checks.length === 0
+    )
+      fail("duplicate or malformed requirement declaration");
+    const entries = new Map();
+    for (const id of requirement.checks) {
+      if (!nonempty(id) || checks.has(id)) fail("duplicate or malformed assertion declaration");
+      checks.add(id);
+      entries.set(id, { passed: 0, failed: 0 });
+    }
+    requirements.set(requirement.id, entries);
+  }
+  for (const phase of report.phases) {
+    if (!Array.isArray(phase.requirements) || phase.requirements.length !== requirements.size)
+      fail(`missing requirement inventory in ${phase.phase}`);
+    const seenRequirements = new Set();
+    for (const requirement of phase.requirements) {
+      const expected = requirements.get(requirement?.id);
+      if (
+        !expected ||
+        seenRequirements.has(requirement.id) ||
+        !Array.isArray(requirement.checks) ||
+        requirement.checks.length !== expected.size
+      )
+        fail(`requirement inventory mismatch in ${phase.phase}`);
+      seenRequirements.add(requirement.id);
+      const seenChecks = new Set();
+      for (const check of requirement.checks) {
+        const total = expected.get(check?.id);
+        if (!total || seenChecks.has(check.id) || !count(check.passed) || !count(check.failed))
+          fail(`assertion inventory or counts invalid in ${phase.phase}`);
+        if (phase.status === "passed" && check.failed > 0)
+          fail("passed phase contains failed assertions");
+        seenChecks.add(check.id);
+        total.passed += check.passed;
+        total.failed += check.failed;
+        if (!count(total.passed) || !count(total.failed)) fail("assertion counts overflow");
+      }
+    }
+  }
+  const results = [];
+  for (const [requirementId, entries] of requirements) {
+    for (const [checkId, counts] of entries) {
+      results.push({
+        file,
+        fullName: assertionFullName(requirementId, checkId),
+        outcome: counts.failed ? "failed" : counts.passed ? "passed" : "skipped",
+        detail:
+          `Assertion ${checkId}: ${counts.passed} passed, ${counts.failed} failed invocations across paths and property, including shrinking.`.slice(
+            0,
+            4000,
+          ),
+      });
+    }
+  }
+  const missing = results.filter((result) => result.outcome === "skipped");
+  const inconclusive = report.phases.filter((phase) => phase.status === "inconclusive");
+  const discrepancy = report.phases.some((phase) => phase.status === "discrepancy");
+  const missingIds = [...requirements.values()].flatMap((entries) =>
+    [...entries].filter(([, counts]) => counts.passed + counts.failed === 0).map(([id]) => id),
+  );
+  for (const phase of report.phases) {
+    if (
+      phase.requirementGaps !== undefined &&
+      (discrepancy ||
+        phase.phase !== "property" ||
+        phase.status !== "inconclusive" ||
+        !Array.isArray(phase.requirementGaps) ||
+        phase.requirementGaps.length === 0 ||
+        results.some((result) => result.outcome === "failed") ||
+        new Set(phase.requirementGaps).size !== phase.requirementGaps.length ||
+        JSON.stringify([...phase.requirementGaps].sort()) !==
+          JSON.stringify([...missingIds].sort()))
+    )
+      fail("requirement gap marker conflicts with unevaluated assertions");
+  }
+  const coverageOnly =
+    inconclusive.length > 0 && inconclusive.every((phase) => phase.requirementGaps !== undefined);
+  const detail = report.phases
+    .filter((phase) => phase.status !== "passed")
+    .map((phase) => `${phase.phase}: ${phase.message}`)
+    .join("\n");
+  results.push({
+    file,
+    fullName: executionFullName,
+    outcome:
+      inconclusive.length && !coverageOnly
+        ? "error"
+        : discrepancy
+          ? "failed"
+          : missing.length
+            ? "skipped"
+            : "passed",
+    detail: (
+      detail ||
+      (missing.length
+        ? "Required assertions were not executed."
+        : "Native paths and property execution passed.")
+    ).slice(0, 4000),
+  });
+  return results;
+}