@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.1

package/dist/utils/output.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The one place a command's result reaches stdout (#639).
+ *
+ * With `--json`, or `SERIOUSGAMING_JSON=1` in the environment, every command
+ * writes exactly one JSON document to stdout, whether it succeeded or failed:
+ *
+ *     { "ok": true,  "command": "tick", "data": {...}, "diagnostics": [], "warnings": [] }
+ *     { "ok": false, "command": "build", "error": { "code", "message", "hint"? },
+ *       "diagnostics": [], "warnings": [] }
+ *
+ * Commands do not print the envelope themselves. They hand their result to
+ * {@link reportResult}, with a printer for the human form, and throw a
+ * {@link CliError} to fail. The single catch in `cli.ts` finishes the command
+ * here, which is what makes 'one document' a guarantee rather than a habit:
+ * while JSON mode is on, anything else written to stdout (a stray
+ * `console.log`, commander's help) is moved to stderr.
+ */
+import { CliError, type Diagnostic } from './cli-error';
+import { type ErrorCode } from './error-codes';
+/** The environment variable that turns JSON output on for every command. */
+export declare const JSON_ENV_VAR = "SERIOUSGAMING_JSON";
+export interface Warning {
+    message: string;
+    code?: string;
+}
+export interface SuccessEnvelope {
+    ok: true;
+    command: string;
+    data: unknown;
+    /** Findings that did not fail the command: warnings anchored to a file. */
+    diagnostics: Diagnostic[];
+    warnings: Warning[];
+}
+export interface FailureEnvelope {
+    ok: false;
+    command: string;
+    error: {
+        code: ErrorCode;
+        message: string;
+        hint?: string;
+        details?: Record<string, unknown>;
+    };
+    diagnostics: Diagnostic[];
+    warnings: Warning[];
+}
+export type Envelope = SuccessEnvelope | FailureEnvelope;
+/**
+ * Ask the top-level handler to end the process once the command has finished,
+ * rather than waiting for the event loop to drain. For `dev`, whose servers
+ * hold handles open after a stop or a failed start. Commands never call
+ * `process.exit` themselves.
+ */
+export declare function requestProcessExit(): void;
+export declare function processExitRequested(): boolean;
+/** Whether `SERIOUSGAMING_JSON` asks for JSON output. */
+export declare function jsonRequestedByEnvironment(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Start a command's output. In JSON mode stdout is held for the envelope, and
+ * everything else written to it goes to stderr until the command finishes.
+ */
+export declare function beginCommand(command: string, json: boolean): void;
+/** The command path, once the parser knows it for certain. */
+export declare function setCommandPath(command: string): void;
+/** Turn JSON mode on for a command already begun, such as from a `--json` flag. */
+export declare function enableJsonOutput(): void;
+export declare function isJsonOutput(): boolean;
+/**
+ * Report what the command produced: the envelope's `data` in JSON mode, or
+ * whatever `human` prints otherwise. A command that reports nothing has
+ * `data: null`.
+ */
+export declare function reportResult(data: unknown, human?: () => void): void;
+/** Print a value as JSON on stdout, two-space indented, as every command does. */
+export declare function printJson(value: unknown): void;
+/** A notice the caller should see, carried in the envelope's `warnings`. */
+export declare function recordWarning(message: string, code?: string): void;
+/** Whether the command has already recorded a warning with this code. */
+export declare function hasWarning(code: string): boolean;
+/**
+ * A finding that does not fail the command, such as a build warning: carried
+ * in the envelope's `diagnostics`. The command prints its own human form.
+ */
+export declare function recordDiagnostic(diagnostic: Diagnostic): void;
+/** Write the success envelope (JSON mode) and release stdout. */
+export declare function finishSuccess(): void;
+/**
+ * Report a failure: the failure envelope on stdout in JSON mode, a message on
+ * stderr otherwise. Returns the exit code its category maps to.
+ */
+export declare function finishFailure(error: unknown): number;
+/**
+ * The human form of a failure's located diagnostics: `  at file:line:column`
+ * under the message, one per finding that names a file. A finding without a
+ * file is already in the message a command builds from its findings.
+ */
+export declare function locatedDiagnostics(diagnostics: readonly Diagnostic[]): string[];
+/** The envelope a finished JSON command printed, for tests reading it back. */
+export declare function parseEnvelope(stdout: string): Envelope;
+/**
+ * Every failure as a {@link CliError}. A parse error from commander is a usage
+ * error; anything else that is not a `CliError` is a bug in the CLI, exit 1.
+ */
+export declare function toCliError(error: unknown): CliError;
+/** Commander's own errors, recognised by shape so no realm or copy matters. */
+export declare function commanderError(error: unknown): {
+    code: string;
+    exitCode: number;
+    message: string;
+} | null;

package/dist/utils/platform.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared helpers for talking to the Serious Gaming platform API.
+ *
+ * Every platform endpoint lives under `<host>/api/v0/...` and authenticates
+ * with an `Authorization: Bearer <apiKey>` header. The host is just the
+ * origin; callers append the API path themselves.
+ */
+export declare const DEFAULT_PLATFORM_HOST = "https://app.businesssimulations.com";
+export declare function normalisePlatformHost(url: string): string;
+export interface PlatformErrorBody {
+    errors?: unknown;
+    message?: unknown;
+}
+export declare function formatPlatformErrors(body: PlatformErrorBody): string;

package/dist/utils/prompt.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Every interactive prompt the CLI shows, behind one gate (#639).
+ *
+ * A prompt is shown only when somebody can answer it: stdin and stdout are
+ * both terminals, JSON output is off and `CI` is unset. Anywhere else the
+ * prompt is a usage error naming the question and how to pass the answer
+ * instead, rather than a command that waits on a pipe forever or reads
+ * garbage from one.
+ *
+ * Import prompts from here, never from `@inquirer/prompts` directly.
+ */
+import * as inquirer from '@inquirer/prompts';
+export declare function canPrompt(): boolean;
+/** For tests that drive the prompts through a mock: force the gate open or shut. */
+export declare function setInteractiveOverride(value: boolean | null): void;
+/** `--yes`: answer every confirmation with yes. */
+export declare function setAssumeYes(value: boolean): void;
+/**
+ * How to run the current command without prompts, quoted in the error when a
+ * prompt is refused.
+ */
+export declare function setPromptUsage(value: string | undefined): void;
+export declare const input: typeof inquirer.input;
+export declare const select: typeof inquirer.select;
+export declare const checkbox: typeof inquirer.checkbox;
+/** A yes/no question that is part of the input, such as 'Add another property?'. */
+export declare const confirm: typeof inquirer.confirm;
+/**
+ * 'Are you sure?': a confirmation `--yes` answers. Without a terminal and
+ * without `--yes` it is a usage error, so a script never deletes by accident
+ * and never hangs on the question.
+ */
+export declare function confirmAction(config: {
+    message: string;
+    default?: boolean;
+}, yes?: boolean): Promise<boolean>;

package/dist/utils/real-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A path with its symbolic links resolved, as esbuild reports them, so a
+ * package under a linked directory (macOS's `/var`) still yields a relative
+ * path. The path as given when it does not exist.
+ */
+export declare function realPath(path: string): string;

package/dist/utils/schema-properties.d.ts

@@ -0,0 +1,35 @@
+import type { PropertySchema } from '../prompts/index.js';
+/**
+ * Extract the properties map from a full JSON Schema object.
+ *
+ * Returns an empty object if the schema is undefined or has no properties.
+ */
+export declare function extractSchemaProperties(schema: Record<string, unknown> | undefined): Record<string, PropertySchema>;
+/**
+ * Wrap a flat property map into a full JSON Schema object.
+ *
+ * The wrapped object has `type: 'object'`, all properties marked as required,
+ * and `additionalProperties: false`.
+ */
+export declare function wrapAsFullSchema(properties: Record<string, PropertySchema>): Record<string, unknown>;
+/**
+ * Detect whether a variablesSchema is in the flat shorthand format (property
+ * definitions at the top level) or the full JSON Schema format (with a
+ * `properties` key), and return the full format in both cases.
+ *
+ * **Flat format** (property definitions at the top level):
+ * ```json
+ * { "Price": { "type": "number", "default": 0 } }
+ * ```
+ *
+ * **Full format** (standard JSON Schema object):
+ * ```json
+ * { "type": "object", "properties": { "Price": { "type": "number", "default": 0 } } }
+ * ```
+ *
+ * Heuristic: if the schema already has a `properties` key it is treated as
+ * the full format. Otherwise every top-level value that is a plain object
+ * with a `type` field is assumed to be a property definition, and the schema
+ * is wrapped.
+ */
+export declare function normalizeVariablesSchema(schema: Record<string, unknown> | undefined): Record<string, unknown> | undefined;

package/dist/validation/ajv.d.ts

@@ -0,0 +1,17 @@
+import Ajv from 'ajv';
+/**
+ * Single construction point for Ajv instances (#283). The shape layer
+ * (`cli/validation.ts`) and the semantic layer (`game-validator.ts`) both used
+ * to `new Ajv({ allErrors: true, verbose: true })` independently; they now share
+ * these options so a change (a format, a keyword) is made once. Neither layer
+ * registers formats, so the options are all they share — the two
+ * error-formatting conventions are intentionally left untouched.
+ *
+ * Two keywords are registered, each of which would otherwise fail strict mode
+ * as unknown. `tsType` names the TypeScript type a capability property
+ * generates to (#601) and constrains nothing at run time. `blob` marks an
+ * endpoint request field as a file (§6.12): by the time the schema sees the
+ * request the runtime has resolved every such field to a `blob:` reference,
+ * so the keyword holds it to that.
+ */
+export declare function createAjv(): Ajv;

package/dist/validation/facilitator-guide-validator.d.ts

@@ -0,0 +1,27 @@
+import type { FacilitatorGuideDefinition } from '@seriousgaming/sdk';
+import { referenceLocale } from '../guide/locale.js';
+/**
+ * Facilitator guide content validation.
+ *
+ * Checks the on-disk content of a guide against its definition:
+ * - Locale completeness: each declared locale should mirror the reference
+ *   locale's chapter file set (warnings — fallback handles gaps at runtime)
+ * - Video blocks: provider and parameters must validate against the closed
+ *   provider registry (errors — these render as inert error blocks)
+ * - Referenced assets: relative image references must resolve to a file
+ *   inside the guide directory (errors)
+ *
+ * This is the **semantic / content** layer (the `validation/` directory); the
+ * schema-level bundle-shape check is `validateSDKFacilitatorGuide` in
+ * `cli/validation.ts`.
+ */
+export interface GuideContentValidationResult {
+    errors: string[];
+    warnings: string[];
+}
+export { referenceLocale };
+export declare function validateFacilitatorGuideContent(options: {
+    definition: FacilitatorGuideDefinition;
+    /** Absolute path to the guide's root directory */
+    rootDirectory: string;
+}): GuideContentValidationResult;

package/dist/validation/findings.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Validation findings as data (#639): what is wrong, where, and the code a
+ * script or agent branches on. Each check returns these, and the message text
+ * a person reads is formatted from them rather than the other way round.
+ */
+import type { Diagnostic } from '../utils/cli-error';
+/** A diagnostic before the command decides how serious it is. */
+export type Finding = Omit<Diagnostic, 'severity'> & {
+    severity?: Diagnostic['severity'];
+};
+/** The manifest, relative to the package root. */
+export declare const MANIFEST_FILE = "seriousgaming.sdk.json";
+/**
+ * A resource's bundle file, relative to the package root: the slot's bundle
+ * for the kinds a game holds one of, `<plural>/<identifier>/<bundle>` for the
+ * rest. Undefined for a type that has no bundle of its own.
+ */
+export declare function bundleFileOf(type: string, identifier: string): string | undefined;
+/** One RFC 6901 reference token. */
+export declare function pointerToken(segment: string | number): string;
+/** An RFC 6901 pointer from its segments. */
+export declare function pointerOf(...segments: Array<string | number>): string;
+/**
+ * The closest of `candidates` to `name`, when one is close enough to be the
+ * likely intent: a typo, not a different word. Case is ignored.
+ */
+export declare function closestMatch(name: string, candidates: Iterable<string>): string | undefined;
+/** "Did you mean 'x'?", or undefined when nothing is close. */
+export declare function didYouMean(name: string, candidates: Iterable<string>): string | undefined;
+/** Levenshtein distance, two rows at a time. */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * Split a refusal into the sentence saying what is wrong and the rest, which
+ * says what to do about it. The refusals for removed fields are written that
+ * way, so one string serves the human message and the diagnostic's hint.
+ */
+export declare function splitHint(text: string): {
+    message: string;
+    hint?: string;
+};

package/dist/validation/game-constraints.d.ts

@@ -0,0 +1,10 @@
+import { type GameSettingsSource } from '../core/game-settings';
+import { type Finding } from './findings.js';
+/**
+ * What is wrong with a game's `gameSettingsConstraints` (SPECIFICATION.md
+ * §6.10.1). The manifest's schema already refuses an unknown field or
+ * keyword; what it cannot see is a constraint that widens the SDK's schema
+ * rather than narrowing it, and a game whose own values break its own
+ * constraints, which only the merged schema can judge.
+ */
+export declare function gameConstraintFindings(manifest: GameSettingsSource): Finding[];

package/dist/validation/game-validator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Game validation utilities
+ * Validates engine execution order and capability dependencies
+ *
+ * Part of the **semantic / cross-reference** validation layer (the
+ * `validation/` directory): it checks meaning across resources, not shape.
+ * Per-bundle JSON Schema validation lives in the `validateSDK*` family in
+ * `cli/validation.ts`.
+ */
+import type { SDKGame, SDKEngine, ResolvedPackageManifest } from '@seriousgaming/sdk';
+import { type Finding } from './findings.js';
+export interface ValidationResult {
+    success: boolean;
+    errors: string[];
+    warnings: string[];
+    /**
+     * Some of `errors` and `warnings` as data, each with its code and where it
+     * points (#639). A finding's message is the error or warning it describes,
+     * word for word; the rest are reported without a finer location.
+     */
+    findings?: Finding[];
+    /** The game's engine, once resolved. A game holds exactly one. */
+    engine?: SDKEngine;
+}
+export interface GameEngineResult {
+    success: boolean;
+    engine?: SDKEngine;
+    error?: string;
+}
+/**
+ * The cross-resource rules the schema cannot express, checked across the
+ * whole package once each bundle has passed its own schema.
+ */
+export declare function validateGame(game: SDKGame, config: ResolvedPackageManifest): ValidationResult;

package/dist/validation/package-validation.d.ts

@@ -0,0 +1,41 @@
+import type { ResolvedPackageManifest } from '@seriousgaming/sdk';
+import { type ResourceType } from '../templating/resource-metadata.js';
+import type { Diagnostic } from '../utils/cli-error';
+/**
+ * The static validation `build` runs before it bundles anything, and that the
+ * dev server runs on the package it serves.
+ *
+ * Each kind of resource declares its checks in {@link VALIDATION_DESCRIPTORS};
+ * one loop runs them, in the order the table lists the kinds, and reports one
+ * result per resource. A new kind is validated by adding a row.
+ */
+/** What a validated resource is: a resource type, or the package or game the manifest is. */
+export type ValidatedType = ResourceType | 'package' | 'game';
+export interface ResourceValidationResult {
+    identifier: string;
+    type: ValidatedType;
+    errors: string[];
+    warnings: string[];
+    /** Each error and warning above as a diagnostic, located where the check could say. */
+    diagnostics: Diagnostic[];
+}
+export interface ValidateOutput {
+    success: boolean;
+    resources: ResourceValidationResult[];
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        warnings: number;
+    };
+}
+/** Validate the package at `workingDir`, loading its manifest from `config`. */
+export declare function validatePackage(options: {
+    config: string;
+    workingDir: string;
+}): Promise<ValidateOutput>;
+/** Validate a package already loaded. */
+export declare function validateLoadedPackage(config: ResolvedPackageManifest, options: {
+    configPath: string;
+    workingDir: string;
+}): Promise<ValidateOutput>;

package/dist/validation/package-validator.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Package definition validation
+ *
+ * `schema.json` already enforces a Semantic Versioning 2.0.0 regex on
+ * `PackageDefinition.version`, but the build path reads the value out of
+ * `seriousgaming.sdk.json` and copies it into the bundled manifest without
+ * re-checking it. A hand-edited non-semver value (e.g. `'1.0'`, `'v1.0.0'`)
+ * would otherwise reach the bundle, breaking downstream consumers that order
+ * packages by semver precedence.
+ *
+ * `validatePackageDefinition` runs the same check at build time so the
+ * manifest is guaranteed to carry a valid semver.
+ */
+import type { SDKPackage } from '@seriousgaming/sdk';
+export interface PackageValidationResult {
+    success: boolean;
+    errors: string[];
+}
+export declare function validatePackageDefinition(packageBundle: SDKPackage | undefined): PackageValidationResult;

package/dist/validation/resource-validator.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Resource validation utilities
+ * Validates engines and user interfaces for capability references and file existence
+ *
+ * This is the **semantic / cross-reference** layer: it checks meaning (do
+ * capability references resolve? do declared files exist?), not shape. The
+ * schema-level "does this bundle match its JSON Schema?" check is the
+ * `validateSDK*` family in `cli/validation.ts`.
+ */
+import type { SDKEngine, SDKUserInterface, SDKScenarioEditor, SDKSetup, ResolvedPackageManifest, SDKEndpoint, SDKHook, SDKValidator, SDKTickController } from '@seriousgaming/sdk';
+import { type Finding } from './findings';
+export interface ValidationResult {
+    success: boolean;
+    errors: string[];
+    /**
+     * Some or all of `errors` as data, each with its code and where it points
+     * (#639). A finding's message is the error it describes, word for word.
+     */
+    findings?: Finding[];
+}
+/**
+ * Validate an engine for capability references
+ * Checks that all capabilities in reads/writes exist in the configuration
+ */
+export declare function validateEngine(engine: SDKEngine, config: ResolvedPackageManifest): ValidationResult;
+/**
+ * Validate a user interface for capability references
+ * Checks that all capabilities in reads/writes exist in the configuration.
+ * Each user interface fills a slot, so its identifier is its type.
+ */
+export declare function validateUserInterface(userInterface: SDKUserInterface, config: ResolvedPackageManifest): ValidationResult;
+/**
+ * Validate an endpoint for capability references. Its `writes` are checked
+ * with the game, beside the endpoint's scope.
+ */
+export declare function validateEndpoint(endpoint: SDKEndpoint, config: ResolvedPackageManifest): ValidationResult;
+/**
+ * Validate a hook for capability references — same shape as an engine.
+ */
+export declare function validateHook(hook: SDKHook, config: ResolvedPackageManifest): ValidationResult;
+/**
+ * Validate a validator for capability references. Validators are read-only by
+ * design; the schema rejects `writes` outright.
+ */
+export declare function validateValidator(validator: SDKValidator, config: ResolvedPackageManifest): ValidationResult;
+/**
+ * Validate a tick controller for capability references. Tick controllers are
+ * read-only; the schema does not admit `writes`.
+ */
+export declare function validateTickController(tc: SDKTickController, config: ResolvedPackageManifest): ValidationResult;
+/**
+ * Validate that an engine's logic file exists and exports the pair its shape
+ * requires.
+ *
+ * Which shape that is comes from the same exports (#513): discovery derives
+ * `aggregate` from `InitAggregate` / `RunAggregate`, so there is no
+ * declaration left to contradict the code. What remains is the half-aggregate
+ * engine — one of the pair without the other — which no dispatch rule covers,
+ * and the per-team engine that exports neither and so must export `Run`.
+ * `Init` is never required (§10.1).
+ */
+export declare function validateEngineFiles(engine: SDKEngine, workingDir: string): Promise<ValidationResult>;
+/**
+ * Validate that an endpoint's logic exists and exports what it runs (§6.12):
+ * `Handle`, or `Plan` for one that answers in two phases.
+ *
+ * Discovery has already refused every mix of the three exports, and stamped
+ * `responds` when the endpoint answers in two phases. What is left is the
+ * endpoint that exports neither, which used to load and build cleanly and fail
+ * only when it was first called. Checked here, beside the engine's exports,
+ * rather than at load: a file that does not transpile reports no exports at
+ * all, and at load that would misreport a syntax error as a missing export and
+ * stop the dev server over it.
+ */
+export declare function validateEndpointFiles(endpoint: SDKEndpoint, workingDir: string): Promise<ValidationResult>;
+/**
+ * Validate that a UI's entrypoint file exists
+ */
+export declare function validateUIFiles(ui: SDKUserInterface | SDKSetup | SDKScenarioEditor, workingDir: string): ValidationResult;

package/dist/validation/schema-defaults-validator.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Validate that every `default` declared inside a resource's schemas is a valid
+ * instance of the subschema that declares it (#335).
+ *
+ * Ajv is used elsewhere to check configuration *data* against these schemas,
+ * but nothing checked the schemas' own defaults. A default that violates its
+ * declaring subschema (an object default carrying a property the subschema does
+ * not declare under `additionalProperties: false`, a string default on a numeric
+ * property) therefore passed `sdk build --validate-only` silently and only
+ * surfaced at runtime, where it seeds the initial context or a resolved config.
+ */
+export interface SchemaDefaultsIssue {
+    /** Dotted path to the subschema declaring the default, e.g. `variablesSchema.properties.Company`. */
+    path: string;
+    /** Human-readable reason the default does not satisfy its subschema. */
+    reason: string;
+}
+/**
+ * Check every schema on a resource definition for defaults that violate their
+ * own subschema. Returns one issue per offending default, empty when clean.
+ */
+export declare function findInvalidSchemaDefaults(definition: unknown): SchemaDefaultsIssue[];
+/**
+ * Format the issues for a resource as build error lines.
+ *
+ * `label` is the resource's human type and identifier, e.g.
+ * `Capability "com.example.company"`.
+ */
+export declare function validateSchemaDefaults(label: string, definition: unknown): string[];

package/dist/validation/schema-validation.d.ts

@@ -0,0 +1,115 @@
+import type { ErrorObject } from 'ajv';
+import type { JSONSchema7 } from 'json-schema';
+import { type Finding } from './findings.js';
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    valid: boolean;
+    /** The findings as one message, for a person. */
+    errors?: string;
+    /**
+     * The same failures as data: one per schema error, each with the RFC 6901
+     * pointer AJV reports (its `instancePath`) into the validated value.
+     */
+    findings?: Finding[];
+}
+/** Every AJV error as a finding. */
+export declare function schemaFindings(errors: ErrorObject[] | null | undefined): Finding[];
+/** Validate an SDKCapability */
+export declare const validateSDKCapability: (data: unknown) => ValidationResult;
+/** Validate an SDKSettings (definition with its settingsSchema) */
+export declare const validateSDKSettings: (data: unknown) => ValidationResult;
+/** Validate an SDKEngine (definition + logic + rootDirectory) */
+export declare const validateSDKEngine: (data: unknown) => ValidationResult;
+/** Validate an SDKUserInterface (definition + entrypoint + rootDirectory) */
+export declare const validateSDKUserInterface: (data: unknown) => ValidationResult;
+/** Validate a package manifest, which is also the game it is */
+export declare const validatePackageManifest: (data: unknown) => ValidationResult;
+/** Validate an SDKTickController */
+export declare const validateSDKTickController: (data: unknown) => ValidationResult;
+/** Validate an SDKScenario */
+export declare const validateSDKScenario: (data: unknown) => ValidationResult;
+/** Validate an SDKFacilitatorGuide */
+export declare const validateSDKFacilitatorGuide: (data: unknown) => ValidationResult;
+/** Validate an SDKSetup */
+export declare const validateSDKSetup: (data: unknown) => ValidationResult;
+/** Validate an SDKScenarioEditor */
+export declare const validateSDKScenarioEditor: (data: unknown) => ValidationResult;
+/** Validate an SDKSessionUserInterface */
+export declare const validateSDKSessionUserInterface: (data: unknown) => ValidationResult;
+/** Validate an SDKWaitingRoomUserInterface */
+export declare const validateSDKWaitingRoomUserInterface: (data: unknown) => ValidationResult;
+/** Validate an SDKPresentation */
+export declare const validateSDKPresentation: (data: unknown) => ValidationResult;
+/** Validate an SDKHook */
+export declare const validateSDKHook: (data: unknown) => ValidationResult;
+/** Validate an SDKValidator */
+export declare const validateSDKValidator: (data: unknown) => ValidationResult;
+/** Validate an SDKEndpoint */
+export declare const validateSDKEndpoint: (data: unknown) => ValidationResult;
+/**
+ * Every settings resource's schema, keyed by settings identifier (§8): what an
+ * override source is validated against. One table rather than a per-slot map,
+ * because settings are named by their identifier and a package may hold any
+ * number.
+ */
+export type SettingsSchemas = Record<string, JSONSchema7>;
+/** Each settings resource's schema, from a resolved package. */
+export declare function settingsSchemas(config: {
+    settings?: {
+        definition: {
+            identifier: string;
+            settingsSchema: unknown;
+        };
+    }[];
+}): SettingsSchemas;
+/**
+ * The per-settings-resource errors in a partial override source: a scenario's
+ * `configuration`, or the session layer. One string per failing entry.
+ *
+ * Driven by the override's **keys**, so a key naming a settings resource the
+ * package does not hold is reported rather than skipped: accepting it and then
+ * ignoring it is inert configuration that reads as applied (§8.2).
+ */
+export declare function collectSettingsOverrideErrors(overrides: Record<string, unknown>, schemas: SettingsSchemas): string[];
+/**
+ * The findings in a partial override source, such as a scenario's `settings`:
+ * {@link collectSettingsOverrideErrors} as data. `base` is the pointer of the
+ * override map inside its file (`/definition/settings` for a scenario), so
+ * each finding points at the key or value at fault.
+ */
+export declare function collectSettingsOverrideFindings(overrides: Record<string, unknown>, schemas: SettingsSchemas, base?: string): Finding[];
+/**
+ * Validate a session-override layer against the settings schemas.
+ *
+ * Partial, like every other override source (§8.2): the layer holds what a
+ * session-scoped source supplied and nothing else, so a key it omits falls
+ * through to the layer beneath and must not be faulted as missing.
+ * `additionalProperties` still rejects an undeclared key, and property-level
+ * checks still apply to the keys that are present.
+ */
+export declare function validateSessionOverrides(configuration: unknown, schemas: SettingsSchemas): ValidationResult;
+/**
+ * Validate a partial override source, such as a scenario's `settings`,
+ * against the settings schemas, labelling the result with the source.
+ *
+ * @param sourceLabel human-readable name of the override source, prefixed onto
+ *   the error message (e.g. 'Scenario "hard"')
+ */
+export declare function validateSettingsOverrides(overrides: Record<string, unknown>, schemas: SettingsSchemas, sourceLabel: string): ValidationResult;
+/**
+ * Validate a **partial** settings override against a resource's
+ * `settingsSchema`, returning ajv's errors or `null` when it is valid.
+ *
+ * An override is partial at every depth (§8.2): a key it omits, at the top or
+ * inside an object-valued setting, falls through to the layer beneath and
+ * ultimately its default. So `required` is dropped wherever a key can fall
+ * through (see {@link withoutRequired}), even against a schema still carrying
+ * the top-level `required` that `sdk build` rejects: faulting partial
+ * overrides on it is how #389 broke every scenario, and on a nested one how
+ * #682 broke a setup UI that spread an object. `additionalProperties` (false
+ * by convention) still rejects undeclared keys, and type and value checks
+ * still apply to the keys that are present.
+ */
+export declare function validatePartialOverride(override: unknown, settingsSchema: JSONSchema7): ErrorObject[] | null;

package/dist/validation/semver.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared Semantic Versioning 2.0.0 pattern. The same regex is enforced by
+ * `schema.json` on `PackageDefinition.version`; keeping it in one TypeScript
+ * location stops the build path, the `package version` CLI, and the JSON
+ * schema from drifting apart.
+ *
+ * See https://semver.org/spec/v2.0.0.html
+ */
+export declare const SEMVER_PATTERN: RegExp;