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

package/dist/prompts/schema-builder.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Interactive prompts for building JSON schema properties
+ * Used for capability variables and engine/hook configuration
+ */
+import type { PropertySchema, PromptPropertyOptions, PromptPropertiesOptions, EditPropertyResult, ReviewPropertiesOptions, ReviewPropertiesResult } from './types.js';
+/**
+ * Prompts user to create a single property (variable, setting or schema property)
+ * Returns the property name and schema definition, or null if cancelled
+ */
+export declare function promptForSchemaProperty(options: PromptPropertyOptions): Promise<{
+    name: string;
+    schema: PropertySchema;
+} | null>;
+/**
+ * Prompts user to create multiple properties iteratively
+ * Handles the full loop: add property -> ask for another -> repeat
+ */
+export declare function promptForSchemaProperties(options?: PromptPropertiesOptions): Promise<Record<string, PropertySchema>>;
+/**
+ * Prompts user to edit an existing property
+ * Shows current values as defaults
+ */
+export declare function editSchemaProperty(name: string, currentSchema: PropertySchema): Promise<EditPropertyResult>;
+/**
+ * Reviews and edits multiple existing properties
+ * For each property: Keep / Edit / Delete
+ * Optionally allows adding new properties
+ */
+export declare function reviewSchemaProperties(existingProperties: Record<string, PropertySchema>, options?: ReviewPropertiesOptions): Promise<ReviewPropertiesResult>;

package/dist/prompts/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Type definitions for JSON schema property building
+ */
+/**
+ * Represents a JSON Schema property definition
+ * Used for capability variables and engine/hook configuration fields
+ */
+export interface PropertySchema {
+    type: 'number' | 'string' | 'boolean';
+    description: string;
+    default?: number | string | boolean;
+    minimum?: number;
+    maximum?: number;
+}
+/**
+ * Default values and constraints for number properties
+ */
+export interface NumberPropertyDefaults {
+    default: number;
+    minimum?: number;
+    maximum?: number;
+}
+/**
+ * Default value for string properties
+ */
+export interface StringPropertyDefaults {
+    default: string;
+}
+/**
+ * Default value for boolean properties
+ */
+export interface BooleanPropertyDefaults {
+    default: boolean;
+}
+/**
+ * Context for property prompts
+ * - 'variable': For capability variables
+ * - 'setting': For a settings resource's settingsSchema
+ * - 'property': For any other schema, such as an endpoint's request or response
+ */
+export type PropertyContext = 'variable' | 'setting' | 'property';
+/**
+ * Options for prompting for a single property
+ */
+export interface PromptPropertyOptions {
+    /** Names of existing properties (for duplicate validation) */
+    existingNames: string[];
+    /** Context for display messages */
+    context?: PropertyContext;
+    /** Whether to allow empty/cancel */
+    allowEmpty?: boolean;
+}
+/**
+ * Options for prompting for multiple properties
+ */
+export interface PromptPropertiesOptions {
+    /** Context for display messages */
+    context?: PropertyContext;
+    /** Existing properties to build upon */
+    existingProperties?: Record<string, PropertySchema>;
+    /** Minimum number of properties required */
+    minProperties?: number;
+}
+/**
+ * Options for editing a property
+ */
+export interface EditPropertyOptions {
+    /** Whether to allow deletion */
+    allowDelete?: boolean;
+}
+/**
+ * Result from editing a property
+ */
+export interface EditPropertyResult {
+    action: 'keep' | 'edit';
+    /** The property as edited, or unchanged when kept */
+    schema: PropertySchema;
+    /** The fields that changed; empty when kept */
+    changes: string[];
+}
+/**
+ * Options for reviewing multiple properties
+ */
+export interface ReviewPropertiesOptions {
+    /** Whether to allow deletion */
+    allowDelete?: boolean;
+    /** Whether to allow adding new properties */
+    allowAdd?: boolean;
+    /** Context for display messages */
+    context?: PropertyContext;
+}
+/**
+ * Result from reviewing multiple properties
+ */
+export interface ReviewPropertiesResult {
+    /** Updated properties schema */
+    properties: Record<string, PropertySchema>;
+    /** Summary of changes made */
+    changes: {
+        kept: string[];
+        modified: Array<{
+            name: string;
+            changes: string;
+        }>;
+        deleted: string[];
+        added: string[];
+    };
+}

package/dist/prompts/validators.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Validation utilities for JSON schema property building
+ */
+/**
+ * PascalCase regex pattern
+ * Must start with uppercase letter, followed by letters/numbers only
+ */
+export declare const PASCAL_CASE_PATTERN: RegExp;
+/**
+ * Validates a property name (must be PascalCase and not a duplicate)
+ * @param name - The property name to validate
+ * @param existingNames - Array of existing property names
+ * @returns true if valid, or an error message string
+ */
+export declare function validatePropertyName(name: string, existingNames: string[]): true | string;
+/**
+ * Validates a number value input string
+ * @param value - The string value to validate
+ * @param constraints - Optional min/max constraints
+ * @returns true if valid, or an error message string
+ */
+export declare function validateNumberValue(value: string, constraints?: {
+    min?: number;
+    max?: number;
+}): true | string;
+/**
+ * Validates that maximum is greater than or equal to minimum
+ * @param maximum - The maximum value string
+ * @param minimum - The minimum value (already parsed)
+ * @returns true if valid, or an error message string
+ */
+export declare function validateMaximumValue(maximum: string, minimum?: number): true | string;

package/dist/runtime/capability-scope.d.ts

@@ -0,0 +1,6 @@
+import type { CapabilityDefinition } from '@seriousgaming/sdk';
+export type CapabilityScope = NonNullable<CapabilityDefinition['scope']>;
+type ScopeFields = Pick<CapabilityDefinition, 'identifier' | 'scope'>;
+/** A capability's effective scope: `team` unless it declares another. */
+export declare function resolveCapabilityScope(definition: ScopeFields): CapabilityScope;
+export {};

package/dist/runtime/context-merge.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The §9.5 context deep-merge a runtime applies to every context update.
+ *
+ * The UI wrappers in `@seriousgaming/sdk/ui` apply the same
+ * merge to their optimistic local copy, from a private module of their own.
+ * Both must apply identical semantics or a UI sending a minimal patch sees its
+ * local view diverge from the host's until the next snapshot, so
+ * `context-merge.parity.test.ts` holds the two to one table of cases:
+ *
+ * - Plain objects are merged recursively
+ * - Arrays, scalars, `null`, and non-plain objects replace the base value
+ * - `__proto__`, `constructor`, and `prototype` keys are ignored (payloads
+ *   cross an untrusted iframe boundary)
+ *
+ * A deep merge cannot express key deletion, so an update carries deletions
+ * beside the patch rather than inside it (see {@link ContextDeletePath} and
+ * {@link applyContextUpdate}).
+ */
+import type { ContextDeletePath } from '@seriousgaming/sdk';
+export declare function deepMergeContext<T extends Record<string, unknown>>(base: T, patch: Record<string, unknown>): T;
+/**
+ * Apply one context update: merge the patch, then remove the deleted paths.
+ *
+ * Deletions are applied after the merge so a single update can replace an
+ * entry — write the new key, drop the old — without the order of the two
+ * mattering to the caller. Every runtime applying an update MUST use this
+ * order (SPECIFICATION.md §9.5).
+ */
+export declare function applyContextUpdate<T extends Record<string, unknown>>(base: T, patch: Record<string, unknown>, deletes?: readonly ContextDeletePath[]): T;

package/dist/runtime/context-projection.d.ts

@@ -0,0 +1,41 @@
+import type { CapabilityDefinition } from '@seriousgaming/sdk';
+/**
+ * The §7.4 projection shared by the host runtime and anything that composes a
+ * context for a UI surface. A surface receives exactly the capabilities it
+ * declared, and never one whose scope puts it out of reach of every surface.
+ *
+ * Both halves matter for different reasons. The declaration half is a payload
+ * bound: a surface that renders eight capabilities has no use for the other
+ * eight, and in a large cohort those eight ride every push to every
+ * participant (§12.4.2). The scope half is a boundary: a `private` capability
+ * is withheld here as well as rejected at build time, so a gap in validation
+ * cannot leak engine state to a frame.
+ */
+/** The scope fields the projection needs from a capability definition. */
+type ScopeFields = Pick<CapabilityDefinition, 'identifier' | 'scope'>;
+/**
+ * The capability identifiers a surface is entitled to receive: its `reads` and
+ * its `writes`, minus anything whose scope withholds it from every surface.
+ *
+ * `writes` are included because a surface that writes a value almost always
+ * displays it, and because the generated `Context` type is the union of both
+ * (`collectCapabilityScope`). Delivering reads alone would contradict the type
+ * the author is holding: `data.price` would be typed as present and arrive
+ * `undefined` for every write-only decision field. It also has to be present
+ * for the wrapper's optimistic merge to have a base to merge into.
+ */
+export declare function declaredCapabilityIds(args: {
+    reads?: readonly string[];
+    writes?: readonly string[];
+    capabilities?: ReadonlyMap<string, ScopeFields>;
+}): Set<string>;
+/**
+ * Project a context onto the capabilities a surface declared.
+ *
+ * Keys absent from `declared` are omitted rather than blanked: a surface
+ * cannot tell 'withheld' from 'defaulted' if it receives an empty object, and
+ * omission is what makes the payload smaller. A key the context does not carry
+ * is not invented.
+ */
+export declare function projectContext<T extends Record<string, unknown>>(context: T, declared: ReadonlySet<string>): Record<string, unknown>;
+export {};

package/dist/runtime/guarded-callbacks.d.ts

@@ -0,0 +1,15 @@
+import { type ApiUse, type SignatureCallbacks } from '@seriousgaming/sdk';
+/**
+ * Wrap a callbacks object so each API listed in the `ApiUse` enum is only
+ * invocable when the corresponding name appears in `uses`. Undeclared APIs
+ * are replaced by a function that throws {@link UndeclaredApiUseError} when
+ * called.
+ *
+ * Callbacks that fall outside the `ApiUse` enum (e.g. `readAsset`) are passed
+ * through unchanged — they are runtime plumbing rather than externally-visible
+ * APIs.
+ *
+ * Returns the same shape as the input, so wrapped callbacks can be handed
+ * directly to engine / hook / tick-controller logic without further plumbing.
+ */
+export declare function createGuardedCallbacks<T extends Partial<SignatureCallbacks>>(callbacks: T, uses: readonly ApiUse[] | undefined, resourceIdentifier: string): T;

package/dist/runtime/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Runtime helpers: the pieces of a Serious Gaming runtime that sit beside the
+ * specification rather than inside a game.
+ *
+ * Reachable as `@seriousgaming/sdk-tools/runtime`.
+ *
+ * Platform-facing. Game authors never import from here: everything a game
+ * needs is in `@seriousgaming/sdk`. These are what the dev
+ * server's executor, session and build step are made of: the `uses` guard
+ * (§6.11), capability scope (§6.1), the §9.5 context merge, the §7.4 surface
+ * projection, the §11.8 to §11.9 tick-result check, the checks on what logic
+ * returns (§7.4, §10.2, §11.12), and the manifest version and optional
+ * features this runtime serves. The shapes may change in a minor
+ * release.
+ */
+export { createGuardedCallbacks } from './guarded-callbacks.js';
+export { resolveCapabilityScope } from './capability-scope.js';
+export type { CapabilityScope } from './capability-scope.js';
+export { applyContextUpdate, deepMergeContext } from './context-merge.js';
+export { declaredCapabilityIds, projectContext } from './context-projection.js';
+export { validateTickControllerResult } from './tick-validation.js';
+export { assertJsonSerialisable } from '../execution/engine-state.js';
+export { readAggregateResult, readEngineResult, readTickControllerResult, } from '../execution/logic-result.js';
+export type { EngineResultRead } from '../execution/logic-result.js';
+export type { ValidateTickResultOptions } from './tick-validation.js';
+export { MANIFEST_VERSION, SUPPORTED_FEATURES, SUPPORTED_SERVICES, unsupportedFeatures, unsupportedServices, } from './manifest-version.js';
+export type { ServiceDeclaration } from './manifest-version.js';

package/dist/runtime/manifest-version.d.ts

@@ -0,0 +1,55 @@
+import type { ApiUse } from '@seriousgaming/sdk';
+/**
+ * Format version of the built package manifest (`dist/seriousgaming.json`).
+ *
+ * Version 2 carries one of each thing a game holds one of — `game`, `engine`,
+ * `userInterface` and so on — rather than a single-element array plus a
+ * reference back to it (#435).
+ *
+ * Version 3 leaves the manifest's shape alone and changes what the logic in
+ * it returns: engine, hook and endpoint results name their writes under
+ * `capabilities` (#592). The version is how a runtime hosting packages built
+ * before that tells which shape to read.
+ *
+ * The field is optional in the schema so that manifests built before it
+ * existed still validate. Those manifests are version 1: a runtime treats an
+ * absent value as 1 rather than as an error, because published artefacts are
+ * archived and must stay runnable.
+ */
+export declare const MANIFEST_VERSION = 3;
+/**
+ * The optional features this runtime supports, by the names a manifest's
+ * `requires` lists them under.
+ *
+ * Empty in 1.0: the list exists so that a feature can arrive within manifest
+ * version 3 without a new one, and a game that depends on it says so rather
+ * than running half-working on a runtime that lacks it.
+ */
+export declare const SUPPORTED_FEATURES: readonly string[];
+/** The entries of a manifest's `requires` that {@link SUPPORTED_FEATURES} does not list. */
+export declare function unsupportedFeatures(manifest: {
+    requires?: readonly string[];
+}): string[];
+/**
+ * The services this runtime provides, by the `ApiUse` names a resource's
+ * `uses` declares them under (§6.11). Every one: the dev server backs each
+ * with a client, and a call that cannot reach its provider rejects with that
+ * client's typed error rather than the service being absent.
+ */
+export declare const SUPPORTED_SERVICES: readonly ApiUse[];
+/** A resource declaring services, as {@link unsupportedServices} reads it. */
+export interface ServiceDeclaration {
+    definition: {
+        identifier: string;
+        uses?: readonly ApiUse[];
+    };
+}
+/**
+ * The services the given resources declare that `supported` does not list,
+ * each with the identifiers of the resources declaring it, in first-declared
+ * order. A runtime refuses the package when this is not empty (§6.11, §2.6).
+ */
+export declare function unsupportedServices(resources: readonly ServiceDeclaration[], supported?: readonly ApiUse[]): Array<{
+    service: ApiUse;
+    resources: string[];
+}>;

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

@@ -0,0 +1,25 @@
+import type { TickControllerResult } from '@seriousgaming/sdk';
+/**
+ * Options for {@link validateTickControllerResult}.
+ */
+export interface ValidateTickResultOptions {
+    /**
+     * Override for "now" in ms since epoch, used to evaluate the effective
+     * cadence of a scheduled (`nextTickAt`) result. Defaults to `Date.now()`.
+     */
+    now?: number;
+}
+/**
+ * Validate a runtime `TickControllerResult` against the §11.8–§11.9 contract.
+ *
+ * Returns `null` when the result is valid, or a human-readable error message
+ * that names the limit, cites SPECIFICATION.md §11, and points at the helper to
+ * use (never at an exported symbol). The message is suitable for surfacing to
+ * authors at authoring time, in the dev server, or in the build step.
+ *
+ * The dev server and the build step share this one definition. The SDK's
+ * `intervalTick()` / `scheduledTick()` builders validate with a private copy
+ * of their own, held to this one by `tick-validation.parity.test.ts`, so the
+ * builders and the runtime agree on what 'valid' means.
+ */
+export declare function validateTickControllerResult(result: Pick<TickControllerResult, 'intervalMs' | 'nextTickAt'>, options?: ValidateTickResultOptions): string | null;