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

package/LICENSE

@@ -0,0 +1,93 @@
+Serious Gaming SDK Tools Licence
+Version 1.0
+
+Copyright (c) 2026 Redburn Technology Ltd ('Redburn').
+All rights reserved, except as granted below.
+
+1. Definitions
+
+'Software' means the @seriousgaming/sdk-tools package, including its
+command-line tools, development server, documentation and templates,
+in source and compiled form, and any updates to it.
+
+'Game' means a simulation package that you create using the Software.
+
+'Output' means files the Software generates or copies into your project,
+including scaffolded resources, templates, the starter game, generated
+types, build output and packaged bundles.
+
+'Platform' means the Serious Gaming platform operated by Redburn, and any
+other service Redburn authorises in writing.
+
+'You' means the individual or organisation using the Software.
+
+2. Licence
+
+Subject to these terms, Redburn grants you a worldwide, non-exclusive,
+non-transferable, royalty-free licence to install and use the Software to
+develop, test, preview, build, package and publish Games for the
+Platform.
+
+3. Your Games and Output
+
+You own the Games you create. Redburn claims no ownership of them. Output
+is licensed to you under the Apache License, Version 2.0, so you may use,
+modify and distribute it as part of your Games.
+
+4. Restrictions
+
+You may not:
+
+(a) distribute, sell, rent, lease or sublicense the Software, except that
+    a Game project may declare the Software as a dependency and install it
+    through a package manager or a private package mirror;
+(b) use the Software, or any part of it, to build, operate or test a
+    runtime, platform or service that runs Games, other than the Platform;
+(c) provide the Software to third parties as a hosted or managed service;
+(d) distribute modified versions of the Software. You may modify it for
+    your own internal use;
+(e) remove or alter any licensing, copyright or other notices.
+
+5. Third-party components
+
+The Software includes open-source components that are licensed under
+their own terms. Those terms apply to those components.
+
+6. Feedback
+
+If you give Redburn feedback or suggestions about the Software, Redburn
+may use them without obligation to you.
+
+7. Termination
+
+This licence ends automatically if you breach it. If you stop the breach
+within 30 days of receiving notice of it from Redburn, the licence is
+reinstated. When the licence ends, you must stop using the Software.
+Section 3 survives termination for Output you already have.
+
+8. No warranty
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+9. Limitation of liability
+
+TO THE EXTENT PERMITTED BY LAW, REDBURN IS NOT LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY ARISING FROM THE SOFTWARE OR ITS USE. Nothing
+in this licence limits liability that cannot be limited by law.
+
+10. Changes
+
+Redburn may publish later versions of the Software under different terms.
+Versions you have already received remain under the terms they were
+published with.
+
+11. Governing law
+
+This licence is governed by the laws of Northern Ireland. The courts of
+Northern Ireland have exclusive jurisdiction over any dispute arising
+from it, except that Redburn may seek an injunction or other urgent
+relief in any court of competent jurisdiction.
+
+Questions: jamie@redburntechnology.com

package/README.md

@@ -1,3 +1,37 @@
-# Temporary Holding Version
+# @seriousgaming/sdk-tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The tools for building Serious Gaming games: the `seriousgaming-sdk` command, the dev server and its console, scaffolding and templates, the build, the test helpers, and the documentation.
+
+```bash
+pnpm add -D @seriousgaming/sdk-tools
+```
+
+To start a new game, run it without installing:
+
+```bash
+pnpm dlx @seriousgaming/sdk-tools new package
+```
+
+The scaffolded package installs this package beside `@seriousgaming/sdk`, which it needs at the same version. The documentation ships inside the package, matched to its version and readable offline: start at `dist/docs/index.md`, or run `pnpm run sdk docs view`.
+
+## Stability
+
+From 1.0.0, these follow semantic versioning. A breaking change waits for a major release:
+
+| Surface                         | What it holds                                                                                         |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| The `seriousgaming-sdk` command | Commands, flags, the JSON result envelope, exit codes and error codes. Message text is not part of it |
+| `./client`                      | `createTestSession`, `startDevServer`, `FakeClock`, the stub services and their types                 |
+
+These exist for the Serious Gaming platform and this repository's own tooling, not for games, and clause 4(b) of the licence does not allow you to use them to build any other runtime. They are versioned with the package but may change in a minor release:
+
+| Subpath     | What it holds                                                                                      |
+| ----------- | -------------------------------------------------------------------------------------------------- |
+| `./host`    | The host half of the iframe protocol and its wire types                                            |
+| `./runtime` | The `uses` guard, the context merge and projection, the tick-result check and the manifest version |
+
+Everything else in the package is internal: `dist/cli.js` and the other bundles, the dev console, and the layout of `dist/`. The exceptions are `dist/docs/` and `dist/templates/package/`, which you may read and copy from, though their contents change with every release.
+
+## Licence
+
+The Serious Gaming SDK Tools Licence, in `LICENSE`. In short: you may install and use the package to build, test and publish games for the Serious Gaming platform, and you own the games you make. Files it generates or copies into your project are yours under the Apache License, Version 2.0. You may not redistribute the package, or use it to build or run another runtime for games. The licence text, not this summary, is what applies.

package/dist/bundling/logic-exports.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Which named functions a logic entrypoint exports.
+ *
+ * Two callers need the same fact and must not disagree about it: discovery
+ * derives an engine's `aggregate` from its exports (#513), and validation
+ * checks that the exports the derived shape requires are all there. A second
+ * implementation of the scan would be a second answer.
+ */
+import { type Diagnostic } from '../utils/cli-error';
+/**
+ * Report what is present rather than what is missing, so one transpile answers
+ * every question a caller has about the file. A transpile failure reports
+ * nothing as present, which leaves a required export reading as missing and
+ * the file reading as non-aggregate: validation then fails on the export it
+ * cannot see. The one failure validation reports in its own words is an
+ * imported Node built-in, carried in `failure`, since no export is missing.
+ */
+export interface LogicExports {
+    /** Whether the entrypoint exists at all. */
+    exists: boolean;
+    /** The subset of the requested names the transpiled output exports. */
+    present: Set<string>;
+    /** Why the file did not transpile, when it did not. */
+    failure?: string;
+    /** The same failure located: file (relative to the package root), line and column. */
+    failureDiagnostics?: Diagnostic[];
+}
+/**
+ * Detect `names` among the exports of the bundle `filePath` transpiles to.
+ *
+ * esbuild emits CJS exports in three shapes depending on how the source
+ * declared them, so each name is looked for in all three.
+ */
+export declare function readLogicExports(filePath: string, names: string[], packageRoot?: string): Promise<LogicExports>;

package/dist/bundling/node-builtins.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Game logic runs on the ECMAScript intrinsics alone (SPECIFICATION.md §3.2),
+ * so a Node built-in it imports works in development, where esbuild leaves it
+ * to Node's `require`, and fails in production, where there is no `require`.
+ * Refusing the import when the logic is bundled closes that gap at the first
+ * build rather than the first live session.
+ */
+import type { Message, Plugin } from 'esbuild';
+/** The code a refused built-in import carries in its message. */
+export declare const LOGIC_NODE_BUILTIN = "LOGIC_NODE_BUILTIN";
+/** Whether `specifier` names a Node built-in: `node:*`, a bare name, or a subpath of one. */
+export declare function isNodeBuiltin(specifier: string): boolean;
+/** The refusal for the file at `where` importing `specifier`. */
+export declare function nodeBuiltinMessage(where: string, specifier: string): string;
+/** An esbuild plugin failing the bundle on any import of a Node built-in. */
+export declare function refuseNodeBuiltins(): Plugin;
+/**
+ * The refusals among an esbuild failure's errors, each naming the file, line
+ * and column of the import, or none when the failure is something else.
+ */
+export declare function nodeBuiltinRefusals(errors: readonly Message[]): string[];

package/dist/bundling/transpiler.d.ts

@@ -0,0 +1,7 @@
+import { TranspileOptions } from '../types';
+export declare function Transpile({ entrypoint, sourcemap, packageRoot, }: TranspileOptions): Promise<string>;
+/**
+ * A path as a diagnostic names it: relative to the package root, with forward
+ * slashes. esbuild reports paths relative to the process's working directory.
+ */
+export declare function packageRelativePath(file: string, packageRoot: string): string;