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

package/dist/docs/cli-error-codes.md

@@ -0,0 +1,156 @@
+<!-- Generated by `pnpm docs:generate` from `sdk-tools/cli/utils/error-codes.ts` and `sdk-tools/docs-partials/cli-error-codes/`. Edit those, not this file. -->
+
+# CLI error codes
+
+Every code a failed `seriousgaming-sdk` command can report. A failure carries one code, as `error.code` in the [JSON envelope](./cli-reference.md#json-output) and in the `Error:` line on stderr, and exits with the exit code of the code's category.
+
+The codes are the contract: branch on the code, never on the message. A code is never renamed or moved to another category without a major version. The meaning of each exit code, and examples of each kind of failure, are in [Exit codes](./cli-reference.md#exit-codes).
+
+## Exit codes by category
+
+| Exit code | Category      | Meaning             | Codes |
+| --------- | ------------- | ------------------- | ----- |
+| 1         | `internal`    | Internal error      | 1     |
+| 2         | `usage`       | Usage error         | 15    |
+| 3         | `package`     | Invalid package     | 29    |
+| 4         | `refused`     | Refused by the game | 11    |
+| 5         | `environment` | Environment         | 18    |
+
+## Codes
+
+A code marked as a diagnostic also appears in a failure's `diagnostics`, one finding each, located in a file. See [Diagnostics](./cli-reference.md#diagnostics).
+
+### Exit 1: internal error
+
+| Code       | When                                                    | Also a diagnostic |
+| ---------- | ------------------------------------------------------- | ----------------- |
+| `INTERNAL` | An unexpected failure inside the CLI. Please report it. |                   |
+
+### Exit 2: usage error
+
+| Code                     | When                                                                                                                                    | Also a diagnostic |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `USAGE_UNKNOWN_COMMAND`  | The command or subcommand does not exist.                                                                                               |                   |
+| `USAGE_REMOVED_COMMAND`  | The command was removed in an earlier release; the hint names what replaces it.                                                         |                   |
+| `USAGE_BAD_FLAG`         | A flag is unknown, has a value the command cannot use, or is combined with one it cannot be.                                            |                   |
+| `USAGE_BAD_ARGUMENT`     | A positional argument has a value the command cannot use.                                                                               |                   |
+| `USAGE_MISSING_ARGUMENT` | A required argument or flag was not given.                                                                                              |                   |
+| `USAGE_MISSING_INPUT`    | The command needs input (a JSON definition, settings or a patch) and none was given as an argument, with --file or on stdin.            |                   |
+| `USAGE_NOT_APPLICABLE`   | The command or flag does not apply to this package or session, such as --team on a single-team game.                                    |                   |
+| `PROMPT_REQUIRED`        | The command would have to ask a question, and prompts are off: there is no terminal, --json or SERIOUSGAMING_JSON is set, or CI is set. |                   |
+| `INPUT_INVALID`          | Input given to the command is not valid JSON, or does not match the shape it must have.                                                 |                   |
+| `FILE_NOT_FOUND`         | A file named on the command line does not exist or cannot be read.                                                                      |                   |
+| `RESOURCE_TYPE_UNKNOWN`  | The resource type does not exist, or does not support this operation.                                                                   |                   |
+| `RESOURCE_NOT_FOUND`     | The package has no resource of that type with that identifier.                                                                          |                   |
+| `RESOURCE_EXISTS`        | A resource with that identifier, or in that slot, already exists.                                                                       |                   |
+| `BUILD_NOT_FOUND`        | The build output or bundle the command reads is missing. Run `build` (or `package bundle`) first.                                       |                   |
+| `PUBLISHER_MISSING`      | No publisher was given with --publisher, SERIOUSGAMING_PUBLISHER or platform.defaultPublisher.                                          |                   |
+
+### Exit 3: invalid package
+
+| Code                          | When                                                                                                                                                  | Also a diagnostic |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `PACKAGE_INVALID`             | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet.                                 | Yes               |
+| `MANIFEST_NOT_FOUND`          | There is no seriousgaming.sdk.json (or package.json) where the command looked.                                                                        |                   |
+| `MANIFEST_INVALID`            | seriousgaming.sdk.json or package.json cannot be read, or is not valid.                                                                               |                   |
+| `BUNDLE_INVALID`              | A resource's bundle file (such as engine.sdk.json) cannot be read, or is not valid.                                                                   |                   |
+| `LOGIC_NODE_BUILTIN`          | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone.                                       | Yes               |
+| `LOGIC_BUNDLE_FAILED`         | A logic file does not bundle: a syntax error, or an import that does not resolve.                                                                     | Yes               |
+| `SCHEMA_INVALID`              | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value.                                                   | Yes               |
+| `JSON_INVALID`                | A bundle file is not valid JSON.                                                                                                                      | Yes               |
+| `BUNDLE_MISSING`              | A resource directory holds no bundle file.                                                                                                            | Yes               |
+| `REMOVED_FIELD`               | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it.                                                     | Yes               |
+| `LAYOUT_OUTDATED`             | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now.                                         | Yes               |
+| `FEATURE_UNSUPPORTED`         | The manifest's `requires` names an optional feature this version of the SDK does not support.                                                         | Yes               |
+| `REFERENCE_UNKNOWN`           | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare.                                      | Yes               |
+| `SETTINGS_UNKNOWN`            | A scenario overrides a settings resource the package does not declare.                                                                                | Yes               |
+| `SETTINGS_UNKNOWN_KEY`        | A scenario overrides a key that its settings resource does not declare.                                                                               | Yes               |
+| `SETTINGS_INVALID`            | A scenario's override does not match its settings resource's schema.                                                                                  | Yes               |
+| `SETTINGS_RESERVED`           | A settings resource is named `game`, which is reserved for the built-in game settings.                                                                | Yes               |
+| `SETTINGS_LOCKED`             | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`.                               | Yes               |
+| `GAME_CONSTRAINT_INVALID`     | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it.                                             | Yes               |
+| `GAME_CONSTRAINT_VIOLATED`    | The game's own value for a `game` setting breaks its `gameSettingsConstraints`.                                                                       | Yes               |
+| `LOGIC_EXPORT_MISSING`        | A logic file is missing, or does not export the functions its resource needs.                                                                         | Yes               |
+| `READ_NEVER_WRITTEN`          | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults.                                           | Yes               |
+| `NO_TERMINATION`              | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it.                                                 | Yes               |
+| `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it.                                   | Yes               |
+| `EDITOR_ENDPOINT_STATEFUL`    | The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have.                    | Yes               |
+| `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments. | Yes               |
+| `ENDPOINT_UNREQUESTED`        | A warning: an internal endpoint no user interface lists in its `endpoints`.                                                                           | Yes               |
+| `PLATFORM_REJECTED`           | The platform refused the uploaded package as invalid.                                                                                                 |                   |
+| `VERSION_EXISTS`              | The platform already has this version of the package. Bump it and publish again.                                                                      |                   |
+
+### Exit 4: refused by the game
+
+| Code                 | When                                                                                                                                                                                                                                                                         | Also a diagnostic |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `REFUSED_DENIED`     | The session refused the command (the 'denied' outcome).                                                                                                                                                                                                                      |                   |
+| `REFUSED_VALIDATION` | A validator rejected the write (the 'validation-rejected' outcome). error.details.rejections lists why.                                                                                                                                                                      |                   |
+| `REFUSED_CONFLICT`   | The write conflicted with a concurrent tick (the 'conflict' outcome).                                                                                                                                                                                                        |                   |
+| `REFUSED_SUPERSEDED` | The write arrived after the tick it was for (the 'superseded' outcome).                                                                                                                                                                                                      |                   |
+| `TICK_FAILED`        | The tick failed, usually because game logic threw (the 'tick-failed' outcome).                                                                                                                                                                                               |                   |
+| `SESSION_ERROR`      | The session failed the command unexpectedly (the 'error' outcome).                                                                                                                                                                                                           |                   |
+| `INVALID_REQUEST`    | The endpoint request failed its requestSchema, so the handler did not run.                                                                                                                                                                                                   |                   |
+| `HANDLER_ERROR`      | The endpoint's handler threw, or ran past its execution bound.                                                                                                                                                                                                               |                   |
+| `INVALID_RESPONSE`   | What the endpoint's handler returned broke its declaration.                                                                                                                                                                                                                  |                   |
+| `LOGIC_ERROR`        | Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at.                           | Yes               |
+| `SETTINGS_STALE`     | The package changed on disk since the session started in a way that applies only at initialisation (a setting, a manifest field such as `teams`, or a capability removed or moved to another scope), so a command that advances or changes play was refused. Run `sdk init`. |                   |
+
+### Exit 5: environment
+
+| Code                      | When                                                                                                                                                  | Also a diagnostic |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `NO_SESSION`              | No dev server is running for this package, and the command will not start one.                                                                        |                   |
+| `SESSION_STALE`           | The running session was started from an out-of-date package and must restart.                                                                         |                   |
+| `LOCK_HELD`               | A dev server is already running for this package.                                                                                                     |                   |
+| `PORT_IN_USE`             | No free port was found to listen on.                                                                                                                  |                   |
+| `DEV_SERVER_OUTDATED`     | The running dev server does not understand the command: it is older than this CLI. Restart it.                                                        |                   |
+| `DEV_SERVER_UNREACHABLE`  | The dev server the lock file names does not answer.                                                                                                   |                   |
+| `DEV_SERVER_UNRESPONSIVE` | A dev server holds the lock and accepts connections but does not answer, most often because logic is stuck in a synchronous loop. Run `sdk dev stop`. |                   |
+| `DEV_SERVER_START_FAILED` | A dev server could not be started.                                                                                                                    |                   |
+| `DEV_SERVER_STOP_FAILED`  | The dev server could not be stopped.                                                                                                                  |                   |
+| `LLM_NOT_CONFIGURED`      | Logic called generateText, and the dev server or in-process session running it has no platform API key configured.                                    |                   |
+| `PLATFORM_UNREACHABLE`    | The Serious Gaming platform could not be reached.                                                                                                     |                   |
+| `PLATFORM_UNAUTHORISED`   | The platform refused the API key, or its holder lacks the role the call needs.                                                                        |                   |
+| `PLATFORM_ERROR`          | The platform failed the request.                                                                                                                      |                   |
+| `API_KEY_MISSING`         | No API key is configured: set SERIOUSGAMING_API_KEY, add it to .env, or pass --api-key.                                                               |                   |
+| `INSTALL_FAILED`          | Installing a new package's dependencies failed.                                                                                                       |                   |
+| `SDK_INCOMPLETE`          | This install of the SDK tools is missing files it ships with, such as its docs.                                                                       |                   |
+| `SETTINGS_FILE_INVALID`   | The global settings file (~/.seriousgaming-sdk/config.json) cannot be parsed.                                                                         |                   |
+| `WRITE_FAILED`            | A file or directory could not be written, moved or removed.                                                                                           |                   |
+
+## Diagnostic codes
+
+The codes a diagnostic carries. `LOGIC_ERROR` is only ever a diagnostic: it sits under the command's `TICK_FAILED`, `SESSION_ERROR`, `HANDLER_ERROR` or `LLM_NOT_CONFIGURED`.
+
+| Code                          | When                                                                                                                                                                                                                                               |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PACKAGE_INVALID`             | The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet.                                                                                                                              |
+| `SCHEMA_INVALID`              | A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value.                                                                                                                                                |
+| `JSON_INVALID`                | A bundle file is not valid JSON.                                                                                                                                                                                                                   |
+| `BUNDLE_MISSING`              | A resource directory holds no bundle file.                                                                                                                                                                                                         |
+| `REMOVED_FIELD`               | A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it.                                                                                                                                                  |
+| `LAYOUT_OUTDATED`             | A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now.                                                                                                                                      |
+| `FEATURE_UNSUPPORTED`         | The manifest's `requires` names an optional feature this version of the SDK does not support.                                                                                                                                                      |
+| `REFERENCE_UNKNOWN`           | A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare.                                                                                                                                   |
+| `SETTINGS_UNKNOWN`            | A scenario overrides a settings resource the package does not declare.                                                                                                                                                                             |
+| `SETTINGS_UNKNOWN_KEY`        | A scenario overrides a key that its settings resource does not declare.                                                                                                                                                                            |
+| `SETTINGS_INVALID`            | A scenario's override does not match its settings resource's schema.                                                                                                                                                                               |
+| `SETTINGS_RESERVED`           | A settings resource is named `game`, which is reserved for the built-in game settings.                                                                                                                                                             |
+| `SETTINGS_LOCKED`             | A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`.                                                                                                                            |
+| `GAME_CONSTRAINT_INVALID`     | A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it.                                                                                                                                          |
+| `GAME_CONSTRAINT_VIOLATED`    | The game's own value for a `game` setting breaks its `gameSettingsConstraints`.                                                                                                                                                                    |
+| `LOGIC_EXPORT_MISSING`        | A logic file is missing, or does not export the functions its resource needs.                                                                                                                                                                      |
+| `LOGIC_NODE_BUILTIN`          | Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone.                                                                                                                                    |
+| `LOGIC_BUNDLE_FAILED`         | A logic file does not bundle: a syntax error, or an import that does not resolve.                                                                                                                                                                  |
+| `READ_NEVER_WRITTEN`          | A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults.                                                                                                                                        |
+| `NO_TERMINATION`              | A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it.                                                                                                                                              |
+| `SCENARIO_EDITOR_UNREACHABLE` | A warning: the game ships a scenario editor but does not set `customScenarios.supported`, so no host ever opens it.                                                                                                                                |
+| `EDITOR_ENDPOINT_STATEFUL`    | The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have.                                                                                                                 |
+| `EXTERNAL_REQUEST_NOT_OBJECT` | An external endpoint's `requestSchema` does not declare `"type": "object"` at the top, which a caller outside the game needs to pass named arguments.                                                                                              |
+| `ENDPOINT_UNREQUESTED`        | A warning: an internal endpoint no user interface lists in its `endpoints`.                                                                                                                                                                        |
+| `LOGIC_ERROR`                 | Game logic (an engine, hook, endpoint, validator or tick controller) threw. A diagnostic, not an error code: it sits in `diagnostics` under the command's TICK_FAILED, SESSION_ERROR or HANDLER_ERROR, with the file, line and column it threw at. |
+
+## Warning codes
+
+A session command also repeats, on stderr and in the envelope's `warnings`, what the dev server could not apply. These are notices, not failures, so they are not in the catalogue above: see [Where the session lives](./cli-reference.md#where-the-session-lives).