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

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+export type TranspileOptions = {
+    entrypoint: string;
+    /**
+     * Append an inline source map, so a stack thrown inside the bundle can be
+     * read back against the source (#639). For logic the dev server runs, never
+     * for a built package.
+     */
+    sourcemap?: boolean;
+    /**
+     * The package root that a failure's diagnostics name files relative to.
+     * Defaults to the working directory.
+     */
+    packageRoot?: string;
+};

package/dist/utils/atomic-write.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Atomic file writes with own-write detection.
+ *
+ * Problem: the dev server watches config/state files with chokidar and also
+ * writes to them. Non-atomic writes (fs.writeFile) can leave truncated files
+ * mid-write, and the watcher can observe our own writes and trigger spurious
+ * reloads. The previous mitigation was a 150ms setTimeout guard, which races
+ * with chokidar's stability threshold.
+ *
+ * Solution:
+ * 1. Write to a sibling temp file, then rename over the destination. `rename`
+ *    is atomic on POSIX and Windows (within the same directory), so readers —
+ *    including the watcher — never observe a partial file.
+ * 2. Hash the content we just wrote and remember it in a small per-path ring
+ *    buffer. When the watcher fires, it can read the file, hash the bytes,
+ *    and skip reloads whose hash matches a recent own-write. No timing window
+ *    to tune.
+ */
+/**
+ * Atomically write `content` to `filePath`.
+ *
+ * Writes to a sibling temp file in the same directory, then renames over the
+ * destination. The parent directory is created if it doesn't exist. Records
+ * the content hash so subsequent watcher events can be identified as our own
+ * writes via {@link isOwnWrite}.
+ */
+export declare function atomicWriteFile(filePath: string, content: string): Promise<void>;
+/**
+ * Returns true if `content` matches a recent own-write of `filePath`.
+ *
+ * Watchers should call this after reading the file from disk to decide
+ * whether an observed change was caused by this process (and therefore
+ * should not trigger a reload).
+ */
+export declare function isOwnWrite(filePath: string, content: string): boolean;
+/**
+ * Clears the recorded own-write hashes for a path (or all paths if omitted).
+ * Intended for tests.
+ */
+export declare function clearOwnWriteHistory(filePath?: string): void;

package/dist/utils/cli-error.d.ts

@@ -0,0 +1,64 @@
+import { type DiagnosticCode, type ErrorCategory, type ErrorCode } from './error-codes';
+/**
+ * One finding about the package, located as precisely as the check that made
+ * it can say (#639). A JSON pointer for a JSON file, a line and column for
+ * TypeScript.
+ */
+export interface Diagnostic {
+    severity: 'error' | 'warning';
+    /** One of `DIAGNOSTIC_CODES` in `error-codes.ts`; the contract, unlike the message. */
+    code: DiagnosticCode;
+    message: string;
+    /** Relative to the package root, with forward slashes. */
+    file?: string;
+    /** RFC 6901, into `file`, when `file` is JSON. */
+    pointer?: string;
+    /** 1-based, when `file` is source code. */
+    line?: number;
+    /** 1-based, when `file` is source code. */
+    column?: number;
+    resource?: {
+        type: string;
+        identifier: string;
+    };
+    hint?: string;
+    /** The tick a logic error was thrown in, when it was thrown in one. */
+    tick?: number;
+    /** The team whose logic threw, when one team's did. */
+    team?: {
+        teamId: string;
+        index: number;
+    };
+}
+/**
+ * Where a diagnostic points, as a person reads it: `file:line:column` for
+ * source, `file#pointer` for JSON, or nothing when it names no file.
+ */
+export declare function diagnosticLocation(diagnostic: Diagnostic): string | undefined;
+export interface CliErrorOptions {
+    /** What to do about it, printed on its own line and carried in the envelope. */
+    hint?: string;
+    diagnostics?: Diagnostic[];
+    /** Structured detail a caller may branch on, such as a validator's rejections. */
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+/**
+ * A command failure, with the stable code a script branches on.
+ *
+ * Command handlers throw this instead of printing and returning (or calling
+ * `process.exit`). The single catch in `cli.ts` turns it into the exit code its
+ * category maps to, and into the failure envelope under `--json`.
+ *
+ * The code is required, so the compiler catches a failure without one. The
+ * message is for people, may span lines, and is not part of the contract.
+ */
+export declare class CliError extends Error {
+    readonly code: ErrorCode;
+    readonly hint: string | undefined;
+    readonly diagnostics: Diagnostic[];
+    readonly details: Record<string, unknown> | undefined;
+    constructor(code: ErrorCode, message: string, options?: CliErrorOptions);
+    get category(): ErrorCategory;
+    get exitCode(): number;
+}

package/dist/utils/document-parser-client.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Document Parser Client - Extracts text content from documents for LLM consumption
+ *
+ * Currently supports PDF files using the unpdf library for local extraction.
+ */
+import type { ExtractTextResponse } from '@seriousgaming/sdk';
+export declare class DocumentParserError extends Error {
+    constructor(message: string);
+}
+export declare class DocumentParserClient {
+    /**
+     * Extract text content from a document.
+     *
+     * @param data - Raw binary data of the document
+     * @param mimeType - MIME type of the document
+     * @returns Extracted text content and source MIME type
+     */
+    extractText(data: Buffer | Uint8Array, mimeType: string): Promise<ExtractTextResponse>;
+    private extractPdf;
+}

package/dist/utils/env-loader.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Environment variable loader
+ *
+ * Loads environment variables from .env file and process environment
+ * Cross-platform compatible (Windows, macOS, Linux)
+ */
+export interface EnvironmentConfig {
+    elevenLabsApiKey?: string;
+    ttsQuickModel?: string;
+    ttsStandardModel?: string;
+    ttsExpertModel?: string;
+    ttsVoicePresets?: Record<string, string>;
+    seriousGamingApiKey?: string;
+    seriousGamingApiHost?: string;
+    defaultPublisher?: string;
+}
+/**
+ * Parse .env file content
+ * Handles comments, empty lines, and quoted values
+ */
+export declare function parseEnvFile(content: string): Record<string, string>;
+/**
+ * Load environment configuration from the global settings file, .env file and
+ * process environment.
+ *
+ * Priority (lowest to highest):
+ * 0. Global settings file (~/.seriousgaming-sdk/config.json)
+ * 1. .env file (if exists)
+ * 2. process.env
+ * 3. flag values
+ *
+ * @param workingDir - Directory to look for .env file
+ * @param flags - CLI flag values (highest priority)
+ * @returns Merged environment configuration
+ */
+export declare function loadEnvironmentConfig(workingDir: string, flags?: {
+    seriousGamingApiKey?: string;
+    seriousGamingApiHost?: string;
+    defaultPublisher?: string;
+}): EnvironmentConfig;

package/dist/utils/error-codes.d.ts

@@ -0,0 +1,335 @@
+/**
+ * Every code a failed command can report, with the category that decides its
+ * exit code.
+ *
+ * The codes are the contract (#639): a script or an agent branches on the
+ * code, never on the message, so a code is never renamed or moved to another
+ * category without a major version. Exported whole so the docs can list it
+ * from the source rather than from a copy (#645).
+ */
+/** What kind of failure a code is, which is what the exit code reports. */
+export type ErrorCategory = 'internal' | 'usage' | 'package' | 'refused' | 'environment';
+/**
+ * The exit code for each category. 0 is success and is no category's.
+ *
+ * - 1 `internal`: a bug in the CLI, never the caller's doing
+ * - 2 `usage`: the command was called wrongly: a bad flag or argument, missing
+ *   input, or a prompt it needs and has no terminal to ask on
+ * - 3 `package`: the package is invalid: schema or validation failures, a
+ *   logic file that will not bundle
+ * - 4 `refused`: the game refused: denied, a validator rejection, a conflict,
+ *   a failed tick, a superseded write
+ * - 5 `environment`: something outside the package: no session, a port in use,
+ *   a lock held, an out-of-date dev server, the platform unreachable
+ */
+export declare const EXIT_CODES: Readonly<Record<ErrorCategory, number>>;
+export interface ErrorCodeEntry {
+    category: ErrorCategory;
+    /** One sentence saying when the code is reported. */
+    description: string;
+}
+export declare const ERROR_CODES: {
+    readonly INTERNAL: {
+        readonly category: "internal";
+        readonly description: "An unexpected failure inside the CLI. Please report it.";
+    };
+    readonly USAGE_UNKNOWN_COMMAND: {
+        readonly category: "usage";
+        readonly description: "The command or subcommand does not exist.";
+    };
+    readonly USAGE_REMOVED_COMMAND: {
+        readonly category: "usage";
+        readonly description: "The command was removed in an earlier release; the hint names what replaces it.";
+    };
+    readonly USAGE_BAD_FLAG: {
+        readonly category: "usage";
+        readonly description: "A flag is unknown, has a value the command cannot use, or is combined with one it cannot be.";
+    };
+    readonly USAGE_BAD_ARGUMENT: {
+        readonly category: "usage";
+        readonly description: "A positional argument has a value the command cannot use.";
+    };
+    readonly USAGE_MISSING_ARGUMENT: {
+        readonly category: "usage";
+        readonly description: "A required argument or flag was not given.";
+    };
+    readonly USAGE_MISSING_INPUT: {
+        readonly category: "usage";
+        readonly description: "The command needs input (a JSON definition, settings or a patch) and none was given as an argument, with --file or on stdin.";
+    };
+    readonly USAGE_NOT_APPLICABLE: {
+        readonly category: "usage";
+        readonly description: "The command or flag does not apply to this package or session, such as --team on a single-team game.";
+    };
+    readonly PROMPT_REQUIRED: {
+        readonly category: "usage";
+        readonly description: "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.";
+    };
+    readonly INPUT_INVALID: {
+        readonly category: "usage";
+        readonly description: "Input given to the command is not valid JSON, or does not match the shape it must have.";
+    };
+    readonly FILE_NOT_FOUND: {
+        readonly category: "usage";
+        readonly description: "A file named on the command line does not exist or cannot be read.";
+    };
+    readonly RESOURCE_TYPE_UNKNOWN: {
+        readonly category: "usage";
+        readonly description: "The resource type does not exist, or does not support this operation.";
+    };
+    readonly RESOURCE_NOT_FOUND: {
+        readonly category: "usage";
+        readonly description: "The package has no resource of that type with that identifier.";
+    };
+    readonly RESOURCE_EXISTS: {
+        readonly category: "usage";
+        readonly description: "A resource with that identifier, or in that slot, already exists.";
+    };
+    readonly BUILD_NOT_FOUND: {
+        readonly category: "usage";
+        readonly description: "The build output or bundle the command reads is missing. Run `build` (or `package bundle`) first.";
+    };
+    readonly PUBLISHER_MISSING: {
+        readonly category: "usage";
+        readonly description: "No publisher was given with --publisher, SERIOUSGAMING_PUBLISHER or platform.defaultPublisher.";
+    };
+    readonly PACKAGE_INVALID: {
+        readonly category: "package";
+        readonly description: "The package fails validation. The diagnostics say where. As a diagnostic code, a finding no finer code describes yet.";
+    };
+    readonly MANIFEST_NOT_FOUND: {
+        readonly category: "package";
+        readonly description: "There is no seriousgaming.sdk.json (or package.json) where the command looked.";
+    };
+    readonly MANIFEST_INVALID: {
+        readonly category: "package";
+        readonly description: "seriousgaming.sdk.json or package.json cannot be read, or is not valid.";
+    };
+    readonly BUNDLE_INVALID: {
+        readonly category: "package";
+        readonly description: "A resource's bundle file (such as engine.sdk.json) cannot be read, or is not valid.";
+    };
+    readonly LOGIC_NODE_BUILTIN: {
+        readonly category: "package";
+        readonly description: "Game logic imports a Node built-in, which is absent in production: logic runs on the JavaScript language alone.";
+    };
+    readonly LOGIC_BUNDLE_FAILED: {
+        readonly category: "package";
+        readonly description: "A logic file does not bundle: a syntax error, or an import that does not resolve.";
+    };
+    readonly SCHEMA_INVALID: {
+        readonly category: "package";
+        readonly description: "A bundle or the manifest does not match the SDK's schema. The diagnostic's pointer names the value.";
+    };
+    readonly JSON_INVALID: {
+        readonly category: "package";
+        readonly description: "A bundle file is not valid JSON.";
+    };
+    readonly BUNDLE_MISSING: {
+        readonly category: "package";
+        readonly description: "A resource directory holds no bundle file.";
+    };
+    readonly REMOVED_FIELD: {
+        readonly category: "package";
+        readonly description: "A bundle or the manifest carries a field the SDK no longer reads. The hint says what replaced it.";
+    };
+    readonly LAYOUT_OUTDATED: {
+        readonly category: "package";
+        readonly description: "A directory or bundle file sits where an earlier version of the SDK kept it. The hint says where it goes now.";
+    };
+    readonly FEATURE_UNSUPPORTED: {
+        readonly category: "package";
+        readonly description: "The manifest's `requires` names an optional feature this version of the SDK does not support.";
+    };
+    readonly REFERENCE_UNKNOWN: {
+        readonly category: "package";
+        readonly description: "A `reads`, `writes`, `settings`, `configures` or `endpoints` entry names something the package does not declare.";
+    };
+    readonly SETTINGS_UNKNOWN: {
+        readonly category: "package";
+        readonly description: "A scenario overrides a settings resource the package does not declare.";
+    };
+    readonly SETTINGS_UNKNOWN_KEY: {
+        readonly category: "package";
+        readonly description: "A scenario overrides a key that its settings resource does not declare.";
+    };
+    readonly SETTINGS_INVALID: {
+        readonly category: "package";
+        readonly description: "A scenario's override does not match its settings resource's schema.";
+    };
+    readonly SETTINGS_RESERVED: {
+        readonly category: "package";
+        readonly description: "A settings resource is named `game`, which is reserved for the built-in game settings.";
+    };
+    readonly SETTINGS_LOCKED: {
+        readonly category: "package";
+        readonly description: "A scenario overrides a setting the game locks with `readOnly`, in its settings schema or its `gameSettingsConstraints`.";
+    };
+    readonly GAME_CONSTRAINT_INVALID: {
+        readonly category: "package";
+        readonly description: "A `gameSettingsConstraints` entry widens the SDK schema for the `game` settings rather than narrowing it.";
+    };
+    readonly GAME_CONSTRAINT_VIOLATED: {
+        readonly category: "package";
+        readonly description: "The game's own value for a `game` setting breaks its `gameSettingsConstraints`.";
+    };
+    readonly LOGIC_EXPORT_MISSING: {
+        readonly category: "package";
+        readonly description: "A logic file is missing, or does not export the functions its resource needs.";
+    };
+    readonly READ_NEVER_WRITTEN: {
+        readonly category: "package";
+        readonly description: "A warning: a resource reads a capability nothing in the package writes, so it only ever holds its defaults.";
+    };
+    readonly NO_TERMINATION: {
+        readonly category: "package";
+        readonly description: "A warning: the game declares neither `maxTicks` nor a tick controller, so only its engine can end it.";
+    };
+    readonly EDITOR_ENDPOINT_STATEFUL: {
+        readonly category: "package";
+        readonly description: "The scenario editor lists an endpoint that declares `reads`, `writes` or `actions`, which need a session the editor does not have.";
+    };
+    readonly EXTERNAL_REQUEST_NOT_OBJECT: {
+        readonly category: "package";
+        readonly description: "An external endpoint's `requestSchema` does not declare `\"type\": \"object\"` at the top, which a caller outside the game needs to pass named arguments.";
+    };
+    readonly ENDPOINT_UNREQUESTED: {
+        readonly category: "package";
+        readonly description: "A warning: an internal endpoint no user interface lists in its `endpoints`.";
+    };
+    readonly PLATFORM_REJECTED: {
+        readonly category: "package";
+        readonly description: "The platform refused the uploaded package as invalid.";
+    };
+    readonly VERSION_EXISTS: {
+        readonly category: "package";
+        readonly description: "The platform already has this version of the package. Bump it and publish again.";
+    };
+    readonly REFUSED_DENIED: {
+        readonly category: "refused";
+        readonly description: "The session refused the command (the 'denied' outcome).";
+    };
+    readonly REFUSED_VALIDATION: {
+        readonly category: "refused";
+        readonly description: "A validator rejected the write (the 'validation-rejected' outcome). error.details.rejections lists why.";
+    };
+    readonly REFUSED_CONFLICT: {
+        readonly category: "refused";
+        readonly description: "The write conflicted with a concurrent tick (the 'conflict' outcome).";
+    };
+    readonly REFUSED_SUPERSEDED: {
+        readonly category: "refused";
+        readonly description: "The write arrived after the tick it was for (the 'superseded' outcome).";
+    };
+    readonly TICK_FAILED: {
+        readonly category: "refused";
+        readonly description: "The tick failed, usually because game logic threw (the 'tick-failed' outcome).";
+    };
+    readonly SESSION_ERROR: {
+        readonly category: "refused";
+        readonly description: "The session failed the command unexpectedly (the 'error' outcome).";
+    };
+    readonly INVALID_REQUEST: {
+        readonly category: "refused";
+        readonly description: "The endpoint request failed its requestSchema, so the handler did not run.";
+    };
+    readonly HANDLER_ERROR: {
+        readonly category: "refused";
+        readonly description: "The endpoint's handler threw, or ran past its execution bound.";
+    };
+    readonly INVALID_RESPONSE: {
+        readonly category: "refused";
+        readonly description: "What the endpoint's handler returned broke its declaration.";
+    };
+    readonly LOGIC_ERROR: {
+        readonly category: "refused";
+        readonly description: "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.";
+    };
+    readonly SETTINGS_STALE: {
+        readonly category: "refused";
+        readonly description: "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`.";
+    };
+    readonly NO_SESSION: {
+        readonly category: "environment";
+        readonly description: "No dev server is running for this package, and the command will not start one.";
+    };
+    readonly SESSION_STALE: {
+        readonly category: "environment";
+        readonly description: "The running session was started from an out-of-date package and must restart.";
+    };
+    readonly LOCK_HELD: {
+        readonly category: "environment";
+        readonly description: "A dev server is already running for this package.";
+    };
+    readonly PORT_IN_USE: {
+        readonly category: "environment";
+        readonly description: "No free port was found to listen on.";
+    };
+    readonly DEV_SERVER_OUTDATED: {
+        readonly category: "environment";
+        readonly description: "The running dev server does not understand the command: it is older than this CLI. Restart it.";
+    };
+    readonly DEV_SERVER_UNREACHABLE: {
+        readonly category: "environment";
+        readonly description: "The dev server the lock file names does not answer.";
+    };
+    readonly DEV_SERVER_UNRESPONSIVE: {
+        readonly category: "environment";
+        readonly description: "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`.";
+    };
+    readonly DEV_SERVER_START_FAILED: {
+        readonly category: "environment";
+        readonly description: "A dev server could not be started.";
+    };
+    readonly DEV_SERVER_STOP_FAILED: {
+        readonly category: "environment";
+        readonly description: "The dev server could not be stopped.";
+    };
+    readonly LLM_NOT_CONFIGURED: {
+        readonly category: "environment";
+        readonly description: "Logic called generateText, and the dev server or in-process session running it has no platform API key configured.";
+    };
+    readonly PLATFORM_UNREACHABLE: {
+        readonly category: "environment";
+        readonly description: "The Serious Gaming platform could not be reached.";
+    };
+    readonly PLATFORM_UNAUTHORISED: {
+        readonly category: "environment";
+        readonly description: "The platform refused the API key, or its holder lacks the role the call needs.";
+    };
+    readonly PLATFORM_ERROR: {
+        readonly category: "environment";
+        readonly description: "The platform failed the request.";
+    };
+    readonly API_KEY_MISSING: {
+        readonly category: "environment";
+        readonly description: "No API key is configured: set SERIOUSGAMING_API_KEY, add it to .env, or pass --api-key.";
+    };
+    readonly INSTALL_FAILED: {
+        readonly category: "environment";
+        readonly description: "Installing a new package's dependencies failed.";
+    };
+    readonly SDK_INCOMPLETE: {
+        readonly category: "environment";
+        readonly description: "This install of the SDK tools is missing files it ships with, such as its docs.";
+    };
+    readonly SETTINGS_FILE_INVALID: {
+        readonly category: "environment";
+        readonly description: "The global settings file (~/.seriousgaming-sdk/config.json) cannot be parsed.";
+    };
+    readonly WRITE_FAILED: {
+        readonly category: "environment";
+        readonly description: "A file or directory could not be written, moved or removed.";
+    };
+};
+export type ErrorCode = keyof typeof ERROR_CODES;
+/**
+ * The codes a diagnostic carries: one finding each, located in a file. A
+ * failure's `error.code` says what kind of failure it was; its diagnostics say
+ * what was found and where. LOGIC_ERROR is only ever a diagnostic.
+ */
+export declare const DIAGNOSTIC_CODES: readonly ["PACKAGE_INVALID", "SCHEMA_INVALID", "JSON_INVALID", "BUNDLE_MISSING", "REMOVED_FIELD", "LAYOUT_OUTDATED", "FEATURE_UNSUPPORTED", "REFERENCE_UNKNOWN", "SETTINGS_UNKNOWN", "SETTINGS_UNKNOWN_KEY", "SETTINGS_INVALID", "SETTINGS_RESERVED", "SETTINGS_LOCKED", "GAME_CONSTRAINT_INVALID", "GAME_CONSTRAINT_VIOLATED", "LOGIC_EXPORT_MISSING", "LOGIC_NODE_BUILTIN", "LOGIC_BUNDLE_FAILED", "READ_NEVER_WRITTEN", "NO_TERMINATION", "EDITOR_ENDPOINT_STATEFUL", "EXTERNAL_REQUEST_NOT_OBJECT", "ENDPOINT_UNREQUESTED", "LOGIC_ERROR"];
+export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
+export declare function categoryOf(code: ErrorCode): ErrorCategory;
+export declare function exitCodeOf(code: ErrorCode): number;
+export declare function isErrorCode(value: unknown): value is ErrorCode;

package/dist/utils/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Helpers for narrowing an unknown caught value to its reportable parts.
+ *
+ * `catch (error: unknown)` is the correct shape, but the
+ * `error instanceof Error ? error.message : 'Unknown error'` extraction it
+ * forces recurs throughout the dev server. This collapses it to one call.
+ */
+/** The message of a caught value, or `fallback` when it carries none. */
+export declare function errorMessage(error: unknown, fallback?: string): string;
+/**
+ * A refusal the caller cannot retry their way out of: the team count is at the
+ * maximum, a shared-state session has already ticked, or the participant named
+ * is not where the caller thinks. Mapped to a terminal `{ kind: 'denied' }`
+ * mutation outcome (SPECIFICATION.md §12.5.1), which tells a surface to explain
+ * itself rather than loop.
+ */
+export declare class DeniedError extends Error {
+    constructor(message: string);
+}

package/dist/utils/global-settings.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Global settings loader
+ *
+ * Reads the user-owned global settings file at `~/.seriousgaming-sdk/config.json`
+ * (override with the `SERIOUSGAMING_SDK_CONFIG` environment variable). The file
+ * stores API keys and defaults once so every project picks them up.
+ *
+ * This is the lowest-priority configuration source: `.env` files, environment
+ * variables, and CLI flags all override it (see env-loader.ts). The file is
+ * plaintext and must not be committed to git.
+ *
+ * Cross-platform: `os.homedir()` resolves the home directory on Windows, macOS
+ * and Linux without any platform branching.
+ */
+import type { GlobalSettings } from '@seriousgaming/sdk';
+/** Environment variable that overrides the global settings file location. */
+export declare const GLOBAL_SETTINGS_ENV_VAR = "SERIOUSGAMING_SDK_CONFIG";
+/**
+ * Resolve the absolute path to the global settings file.
+ *
+ * Uses `SERIOUSGAMING_SDK_CONFIG` if set (which must be an absolute path),
+ * otherwise `~/.seriousgaming-sdk/config.json`.
+ */
+export declare function resolveGlobalSettingsPath(): string;
+/**
+ * Load and parse the global settings file.
+ *
+ * Returns an empty object if the file does not exist. A malformed file is
+ * surfaced as a warning and treated as empty, so a broken global file never
+ * blocks a command that has its keys available from another source.
+ */
+export declare function loadGlobalSettings(path?: string): GlobalSettings;
+/**
+ * Load the settings for a read-modify-write.
+ *
+ * Unlike {@link loadGlobalSettings}, a file that exists but cannot be read or
+ * parsed is an error rather than an empty object. The lenient reader is
+ * correct on the read path, where a broken global file must not block a
+ * command whose keys come from elsewhere; on the write path it would serialise
+ * that empty object back over the file and destroy every key it failed to
+ * parse, which is how a stray `config set` used to take an API key with it
+ * (#538).
+ */
+export declare function loadGlobalSettingsForWrite(path?: string): GlobalSettings;
+/**
+ * Write global settings to disk, creating the parent directory if needed and
+ * applying a restrictive file mode on platforms that support it (POSIX).
+ *
+ * The write goes to a sibling temporary file and is renamed into place, so an
+ * interrupted write cannot leave a truncated settings file behind. A truncated
+ * file is unparseable, and an unparseable file is one a later `config set` has
+ * to refuse rather than repair (#538).
+ */
+export declare function saveGlobalSettings(settings: GlobalSettings, path?: string): void;
+/**
+ * Read a single dot-path value from a settings object. Returns `undefined`
+ * when the key is not set. Throws if the key is not a recognised setting.
+ */
+export declare function getGlobalSetting(settings: GlobalSettings, key: string): string | undefined;
+/**
+ * Return a new settings object with the dot-path key set to `value`,
+ * creating intermediate objects as needed. Throws if the key is not a
+ * recognised setting.
+ */
+export declare function setGlobalSetting(settings: GlobalSettings, key: string, value: string): GlobalSettings;

package/dist/utils/llm-client.d.ts

@@ -0,0 +1,34 @@
+/**
+ * LLM Client - generates text through the Serious Gaming platform's LLM API.
+ *
+ * POSTs spec §17.3 LLMGenerateOptions to `<host>/api/v0/llm/generate`, which
+ * runs the same generateText pipeline production game code uses. Tier-to-model
+ * resolution (with fallback), prompt caching, and content-sequence validation
+ * all happen server-side; this client is a thin authenticated pass-through.
+ */
+import type { LLMGenerateOptions, LLMResponse } from '@seriousgaming/sdk';
+export declare const LLM_NOT_CONFIGURED = "LLM_NOT_CONFIGURED";
+/** How to configure the key, for a command reporting LLM_NOT_CONFIGURED. */
+export declare const LLM_NOT_CONFIGURED_HINT: string;
+export declare class LLMClientError extends Error {
+    /** Set when the failure is the environment's, not the call's. */
+    readonly code?: typeof LLM_NOT_CONFIGURED | undefined;
+    constructor(message: string, 
+    /** Set when the failure is the environment's, not the call's. */
+    code?: typeof LLM_NOT_CONFIGURED | undefined);
+}
+export interface LLMClientConfig {
+    apiKey?: string;
+    apiHost?: string;
+}
+export declare class LLMClient {
+    private apiKey?;
+    private apiHost;
+    constructor(config: LLMClientConfig);
+    /**
+     * Generate text through the platform LLM API.
+     * Supports both simple string prompts and complex options.
+     */
+    generateText(optionsOrPrompt: LLMGenerateOptions | string): Promise<LLMResponse>;
+    private mapErrorMessage;
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Simple logging utility with verbose mode support
+ * Avoids external dependencies by using native console methods
+ */
+export declare function setVerboseMode(verbose: boolean): void;
+export declare function getVerboseMode(): boolean;
+export declare const logger: {
+    /**
+     * Log a message that should always appear (errors)
+     */
+    error: (message: string, ...args: unknown[]) => void;
+    /**
+     * Log a warning message (always appears)
+     */
+    warn: (message: string, ...args: unknown[]) => void;
+    /**
+     * Log a success message (always appears)
+     */
+    success: (message: string, ...args: unknown[]) => void;
+    /**
+     * Log an info message (only in verbose mode)
+     */
+    info: (message: string, ...args: unknown[]) => void;
+    /**
+     * Log a debug message (only in verbose mode)
+     */
+    debug: (message: string, ...args: unknown[]) => void;
+    /**
+     * Log output section header
+     */
+    section: (message: string) => void;
+    /**
+     * Log a blank line (only in verbose mode)
+     */
+    newline: () => void;
+};