gameye-mcp 0.3.2 → 0.5.0

package/README.md

@@ -12,8 +12,23 @@ A [Model Context Protocol](https://modelcontextprotocol.io) server for the [Game
 GAMEYE_API_TOKEN=<your-token> npx -y gameye-mcp
 ```
 
+No Gameye account yet? Start it without a token, `npx -y gameye-mcp`, and your agent can still read the bundled Gameye skills and check a Dockerfile. See [Without a token](#without-a-token).
+
 It needs Node.js 22 or newer. The server speaks MCP over stdio. Normally your MCP client starts it for you (see [Install](#install)), so you rarely need to run it by hand.
 
+## Without a token
+
+You can connect the server before you have a Gameye account. Leave `GAMEYE_API_TOKEN` out of any install below, and the server starts in no-token mode and prints one line on stderr saying so.
+
+- These tools work, and send nothing to the Gameye API: `gameye_context`, `gameye_list_skills` and `gameye_get_skill` (the Gameye skills bundled with the server), `gameye_get_template`, and `gameye_check_dockerfile`. `gameye_update_skills` works too, and reaches GitHub only when called.
+- Every other tool is an account tool. Without a token it sends nothing and returns an error that starts with `Token required:`, then gives the setup steps and the narrowest [token scopes](#token-scopes) for that tool. A `dryRun` call is refused the same way.
+- Every tool result shows `· no token` after the host, for example `[sandbox · api.sandbox-gameye.gameye.net · no token]`, and `gameye_context` reports `Token: not configured`.
+- The instructions the server sends to a connecting agent name the tools that work and tell it to read the `gameye` skill first, then the skill for the game's engine.
+
+To get a token, sign up at [trial.gameye.com](https://trial.gameye.com/?utm_source=github&utm_medium=readme&utm_campaign=gameye-mcp), then in the Gameye Admin Panel open **Users → API tokens** and create one. Self-serve accounts use the sandbox host, which is the server's default.
+
+Set the token where the server is configured: the `env` block of your MCP client's server entry, or `--env` when you add it with `claude mcp add`. The server reads `GAMEYE_API_TOKEN` once when it starts, so restart or reconnect it after you set or change the token. Never paste the token into the chat with your agent.
+
 ## Environments
 
 Gameye has two public API hosts. The server targets **sandbox** by default.
@@ -29,10 +44,14 @@ The environment is a property of the server process. No tool takes an environmen
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
-| `GAMEYE_API_TOKEN` | **Yes** | — | Gameye API token. Use the least-privileged scopes you need (see below). |
+| `GAMEYE_API_TOKEN` | No | — | Gameye API token. Use the least-privileged scopes you need (see [Token scopes](#token-scopes)). Without it the server starts in no-token mode: see [Without a token](#without-a-token). |
 | `GAMEYE_ENV` | No | `sandbox` | `sandbox` or `production`. Selects the API host. |
 | `GAMEYE_API_URL` | No | — | Overrides the host, for testing only. Must be `https`. If it equals one of the two known hosts, it must match `GAMEYE_ENV` or the server refuses to start. Any other URL is labelled `custom` in every tool result. |
 | `GAMEYE_ENABLE_SKILLS_UPDATE` | No | — | Set to `1` to let `gameye_update_skills` run the skills updaters with `apply: true`. Without it the tool only checks and lists the commands. |
+| `GAMEYE_MAX_SESSIONS` | No | `5` | Most sessions launched by this server that may run at once. A launch past it is refused. |
+| `GAMEYE_MAX_TTL` | No | `4h` | Longest `ttl` a launch may ask for, at least `30m`. A longer TTL, or `0`, is refused. |
+| `GAMEYE_MAX_LAUNCHES` | No | `20` | Launches per server run. Restart the server to reset it. |
+| `GAMEYE_STOP_OWN_ONLY` | No | — | Set to `1` so `gameye_stop_session` only stops sessions this server launched. |
 | `GAMEYE_TIMEOUT_MS` | No | `30000` | Per-request timeout in milliseconds, a positive whole number. Log snapshots get at least 60 s and artifact downloads at least 120 s. A request that runs out of time comes back as a tool error: `Request to <host> timed out after <n>s`. |
 
 ## Install
@@ -66,7 +85,7 @@ Most clients (Claude Desktop, Cursor, Windsurf and others) accept an `mcpServers
 
 Restart the client after you change its configuration.
 
-`npx -y gameye-mcp` runs the latest release. To stay on one version, name it: `npx -y gameye-mcp@0.3.2` (or `"args": ["-y", "gameye-mcp@0.3.2"]`).
+`npx -y gameye-mcp` runs the latest release. To stay on one version, name it: `npx -y gameye-mcp@0.4.0` (or `"args": ["-y", "gameye-mcp@0.4.0"]`).
 
 ### Windows
 
@@ -108,7 +127,7 @@ With Claude Code: `claude mcp add gameye --env GAMEYE_API_TOKEN=<your-token> --
 
 - Pass each variable with `-e NAME` (no value), so Docker copies it from the client's environment and the token never appears in the command line.
 - Keep `-i` and never add `-t`: a terminal mangles the JSON-RPC messages on stdout.
-- To stay on one version, use a version tag such as `ghcr.io/gameye/gameye-mcp:0.3.2`.
+- To stay on one version, use a version tag such as `ghcr.io/gameye/gameye-mcp:0.4.0`.
 - Files the server writes stay inside the container, and `--rm` deletes them:
   - `gameye_get_artifacts` saves its download under the temp directory. To keep it, mount a directory and point the temp directory at it: `-v /absolute/dir:/out -e TMPDIR=/out`. The path the tool reports is the container path; the file is in `/absolute/dir` on the host.
   - `gameye_create_token` writes to the `outputPath` you give it. Mount a directory the same way and pass an `outputPath` under `/out`.
@@ -129,29 +148,35 @@ Give the server a token with only the scopes it needs.
 
 ## Available tools
 
-Every tool result starts with the environment and host it used, for example `[sandbox · api.sandbox-gameye.gameye.net]`.
+Every tool result starts with the environment and host it used, for example `[sandbox · api.sandbox-gameye.gameye.net]`. With no token configured it ends with `· no token`: `[sandbox · api.sandbox-gameye.gameye.net · no token]`.
 
-| Tool | Kind | Description |
-|---|---|---|
-| `gameye_context` | read | Show the environment, host and server version this server targets, and the guardrail defaults (session TTL, `launched-by` label, token expiry) |
-| `gameye_launch_session` | write, `dryRun` | Start a containerized game server (billable). Default TTL and agent label applied; see [Guardrails](#guardrails) |
-| `gameye_list_sessions` | read | List running sessions (filterable; `all=true` for every status) |
-| `gameye_describe_session` | read | Get session details, ports and players |
-| `gameye_stop_session` | destructive, `dryRun` | Stop one session by its exact ID |
-| `gameye_player_join` | write | Register one or more players as joined |
-| `gameye_player_leave` | write | Remove one or more players from a session |
-| `gameye_get_locations` | read | List locations that can host an image right now |
-| `gameye_list_regions` | read | List the regions available to your organization |
-| `gameye_check_tag` | read | Check whether an image tag is available in a region |
-| `gameye_list_applications` | read | List your applications with registry, resources, regions and ports |
-| `gameye_list_registry_tags` | read | List an application's tags in its upstream registry (paged) |
-| `gameye_enable_tag` | write, `dryRun` | Enable an image tag for an application so Gameye preloads it |
-| `gameye_get_logs` | read | Fetch session logs |
-| `gameye_get_artifacts` | read | Download a file or directory from a session container as a tar archive |
-| `gameye_create_application` | write, `dryRun` | Create an application |
-| `gameye_edit_application` | destructive, `dryRun` | Change an application; omitted fields stay unchanged |
-| `gameye_create_token` | write, `dryRun` | Create an API token and write it to a file |
-| `gameye_update_skills` | read, or write with `apply` | Compare the installed [Gameye skills](https://github.com/gameye/gameye-skills) with the latest pack, and update them with `apply: true`. See [Keeping the skills current](#keeping-the-skills-current) |
+The Token column names the narrowest [token scope recipe](#token-scopes) each tool needs. Tools marked `none` work without a token.
+
+| Tool | Kind | Token | Description |
+|---|---|---|---|
+| `gameye_context` | read | none | Show the environment, host and server version this server targets, and the guardrail defaults (session TTL, `launched-by` label, token expiry) |
+| `gameye_launch_session` | write, `dryRun` | Operator | Start a containerized game server (billable). Default TTL and agent label applied; see [Guardrails](#guardrails) |
+| `gameye_list_sessions` | read | Observer | List running sessions (filterable; `all=true` for every status) |
+| `gameye_describe_session` | read | Observer | Get session details, ports and players |
+| `gameye_stop_session` | destructive, `dryRun` | Operator | Stop one session by its exact ID |
+| `gameye_player_join` | write | Operator | Register one or more players as joined |
+| `gameye_player_leave` | write | Operator | Remove one or more players from a session |
+| `gameye_get_locations` | read | Observer | List locations that can host an image right now |
+| `gameye_list_regions` | read | Observer | List the regions available to your organization |
+| `gameye_check_tag` | read | Observer | Check whether an image tag is available in a region |
+| `gameye_list_applications` | read | Observer | List your applications with registry, resources, regions and ports |
+| `gameye_list_registry_tags` | read | Observer | List an application's tags in its upstream registry (paged) |
+| `gameye_enable_tag` | write, `dryRun` | Deployer | Enable an image tag for an application so Gameye preloads it |
+| `gameye_get_logs` | read | Observer | Fetch session logs |
+| `gameye_get_artifacts` | read | Observer | Download a file or directory from a session container as a tar archive |
+| `gameye_create_application` | write, `dryRun` | Deployer | Create an application |
+| `gameye_edit_application` | destructive, `dryRun` | Deployer | Change an application; omitted fields stay unchanged |
+| `gameye_create_token` | write, `dryRun` | Token admin | Create an API token and write it to a file |
+| `gameye_update_skills` | read, or write with `apply` | none | Compare the installed [Gameye skills](https://github.com/gameye/gameye-skills) with the latest pack, and update them with `apply: true`. See [Keeping the skills current](#keeping-the-skills-current) |
+| `gameye_list_skills` | read | none | List the Gameye skills bundled with this server, with each skill's version and files |
+| `gameye_get_skill` | read | none | Read a bundled skill's `SKILL.md` or one of its reference files |
+| `gameye_get_template` | read | none | Get the Dockerfile or shutdown-hook template for an Unreal, Unity, Godot or web server, exactly as published in the bundled skill |
+| `gameye_check_dockerfile` | read | none | Check Dockerfile text against the [gameye-containerize](https://github.com/gameye/gameye-skills) container contract, offline: findings with severity, rule, line and fix, plus what the check cannot know |
 
 Every tool carries MCP annotations: read tools set `readOnlyHint`, `gameye_stop_session` and `gameye_edit_application` set `destructiveHint`, and every tool that calls the Gameye API sets `openWorldHint`.
 
@@ -165,7 +190,8 @@ These behave the same on sandbox and production, because sandbox runs live match
 - **Bounded sessions.** A launch without `ttl` gets a `30m` TTL, and the result says the default was applied. Every launch sends the label `launched-by: gameye-mcp`, replacing any `launched-by` value the caller passes, so agent-launched sessions can be found with `gameye_list_sessions` and `filter: { "launched-by": "gameye-mcp" }`. When a warm pool serves the image and region, the Gameye API ignores request labels (and env and args), so warm-pool sessions do not carry this label.
 - **No token in game servers.** A launch is refused, with nothing sent, if any env value or name, arg, or label key or value contains this server's Gameye API token. Env values are never shown in results.
 - **No token in results.** Every tool result, including errors, has this server's API token replaced with `***`, in case log output, labels or an error message echo it.
-- **Explicit stops.** `gameye_stop_session` stops exactly one session by its exact ID. There is no bulk stop, and empty, wildcard or list IDs are refused.
+- **Explicit stops.** `gameye_stop_session` stops exactly one session by its exact ID. There is no bulk stop, and empty, wildcard or list IDs are refused. With `GAMEYE_STOP_OWN_ONLY=1` it also refuses any session this server did not launch.
+- **Session limits.** The Gameye API has no per-token budget, so the server enforces one before it sends a launch. By default an agent can have at most 5 sessions it launched running at once (`GAMEYE_MAX_SESSIONS`), each with a TTL of at most `4h` (`GAMEYE_MAX_TTL`), and at most 20 launches per server run (`GAMEYE_MAX_LAUNCHES`). That caps one run at 20 sessions of 4 hours, 80 session-hours, and 5 at a time. Before each launch the server lists the `launched-by: gameye-mcp` sessions to see which of its own have ended; if that list fails, the launch is refused. Warm-pool sessions carry no label, so they count until their TTL ends. A launch that timed out or got a 5xx may have started, so it counts too. The limits apply to one server process: sessions launched by other agents or tools in your organization don't count, and a restart starts from zero, so set an organization quota in Gameye as well. `gameye_context` shows the limits in force.
 
 ## Keeping the skills current
 
@@ -175,7 +201,7 @@ The [Gameye skills](https://github.com/gameye/gameye-skills) change as the Gamey
 - **skills CLI, this project:** the same, in `skills-lock.json` in the server's working directory.
 - **Claude Code plugin:** `gameye@gameye` in `~/.claude/plugins/installed_plugins.json`.
 
-Without `apply` it only reports. With `apply: true`, and only when the server was started with `GAMEYE_ENABLE_SKILLS_UPDATE=1`, it runs each outdated install's own updater: `npx -y skills@1.7.4 update <the Gameye skills> -g -y` (or `-p -y`), or `claude plugin marketplace update gameye` then `claude plugin update gameye@gameye`. Otherwise it lists those commands for you to run. The updaters get a minimal environment: paths, home, temp, locale, proxy and CA settings and npm and Claude config, never `GAMEYE_*` variables or anything named like a token, secret, password or key. It only updates skills whose lock-file source is `gameye/gameye-skills`, and it never downloads or follows skill text itself. Each command runs with stdin closed and a 90-second limit. On Windows it prints the commands instead of running them. The running agent session keeps the skills it loaded; the next session uses the update. The `gameye` skill tells agents to run the check once per conversation and ask before applying.
+Without `apply` it only reports. With `apply: true`, and only when the server was started with `GAMEYE_ENABLE_SKILLS_UPDATE=1`, it runs each outdated install's own updater: `npx -y skills@1.7.4 update <the Gameye skills> -g -y` (or `-p -y`), or `claude plugin marketplace update gameye` then `claude plugin update gameye@gameye`. Otherwise it lists those commands for you to run. The updaters get a minimal environment: paths, home, temp, locale, proxy and CA settings and npm and Claude config, never `GAMEYE_*` variables or anything named like a token, secret, password or key. It only updates skills whose lock-file source is `gameye/gameye-skills`, and it ships a pinned copy of the skills reviewed at build time: the skill and template tools never fetch skill text at runtime, and only `gameye_update_skills` reaches GitHub, when called. Each command runs with stdin closed and a 90-second limit. On Windows it prints the commands instead of running them. The running agent session keeps the skills it loaded; the next session uses the update. The `gameye` skill tells agents to run the check once per conversation and ask before applying.
 
 ## Telemetry/attribution
 
@@ -203,6 +229,8 @@ A port with `tls: true` has TLS terminated by Gameye on the host. Set it with `g
 
 To teach your agent how to integrate Gameye (session lifecycle, matchmaking, webhooks and more), install the sister project [gameye-skills](https://github.com/gameye/gameye-skills). The skills use these MCP tools when they are available, and fall back to plain HTTP when they aren't.
 
+The server also bundles a pinned copy of the skills, which an agent reads with `gameye_list_skills` and `gameye_get_skill`, with or without a token. If an installed copy is newer, it wins.
+
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).

package/dist/dockerfile-check.d.ts

@@ -0,0 +1,84 @@
+export type Severity = "error" | "warning";
+export type Protocol = "tcp" | "udp";
+export interface DeclaredPort {
+    port: number;
+    protocol: Protocol;
+}
+export interface DockerfileFinding {
+    severity: Severity;
+    code: RuleCode;
+    /** 1-based line where the offending instruction starts. */
+    line: number;
+    message: string;
+    fix: string;
+}
+export interface DockerfileCheckResult {
+    findings: DockerfileFinding[];
+}
+export interface DockerfileRule {
+    code: string;
+    /** Number of the item in the gameye-containerize "container contract" list. */
+    contractNumber: number;
+    /** Text that must appear in that contract item. */
+    keyword: string;
+    severity: Severity;
+}
+export declare const DOCKERFILE_RULES: readonly [{
+    readonly code: "GC1-arm64-platform";
+    readonly contractNumber: 1;
+    readonly keyword: "linux/amd64";
+    readonly severity: "error";
+}, {
+    readonly code: "GC1-windows-base";
+    readonly contractNumber: 1;
+    readonly keyword: "Windows containers";
+    readonly severity: "error";
+}, {
+    readonly code: "GC2-expose-missing";
+    readonly contractNumber: 2;
+    readonly keyword: "EXPOSE";
+    readonly severity: "error";
+}, {
+    readonly code: "GC2-port-mismatch";
+    readonly contractNumber: 2;
+    readonly keyword: "EXPOSE";
+    readonly severity: "error";
+}, {
+    readonly code: "GC2-loopback-bind";
+    readonly contractNumber: 2;
+    readonly keyword: "0.0.0.0";
+    readonly severity: "error";
+}, {
+    readonly code: "GC4-exec-form";
+    readonly contractNumber: 4;
+    readonly keyword: "SIGTERM";
+    readonly severity: "error";
+}, {
+    readonly code: "GC4-npm-start";
+    readonly contractNumber: 4;
+    readonly keyword: "SIGTERM";
+    readonly severity: "error";
+}, {
+    readonly code: "GC7-non-root";
+    readonly contractNumber: 7;
+    readonly keyword: "non-root";
+    readonly severity: "warning";
+}, {
+    readonly code: "GC9-token-in-image";
+    readonly contractNumber: 9;
+    readonly keyword: "API token";
+    readonly severity: "error";
+}];
+export type RuleCode = (typeof DOCKERFILE_RULES)[number]["code"];
+export declare const CANNOT_KNOW: string;
+export interface Instruction {
+    keyword: string;
+    args: string;
+    line: number;
+}
+/** Split Dockerfile text into instructions, joining continuations and skipping comments and heredoc bodies. */
+export declare function parseDockerfile(text: string): Instruction[];
+export declare function checkDockerfile(text: string, opts?: {
+    ports?: DeclaredPort[];
+}): DockerfileCheckResult;
+export declare function formatDockerfileReport(result: DockerfileCheckResult): string;

package/dist/dockerfile-check.js

@@ -0,0 +1,278 @@
+// Offline Dockerfile check against the gameye-containerize container contract.
+//
+// A pure function over Dockerfile text: it reads no files, spawns nothing and
+// makes no request. Each rule cites the numbered contract item it enforces, so
+// a later test can check the numbers against the bundled skill. Any value the
+// check flags as a credential is redacted to `***` here, by the check itself;
+// the server's own token masking does not know about values in user input.
+import { MASK } from "./client.js";
+import { GuardError } from "./guards.js";
+export const DOCKERFILE_RULES = [
+    { code: "GC1-arm64-platform", contractNumber: 1, keyword: "linux/amd64", severity: "error" },
+    { code: "GC1-windows-base", contractNumber: 1, keyword: "Windows containers", severity: "error" },
+    { code: "GC2-expose-missing", contractNumber: 2, keyword: "EXPOSE", severity: "error" },
+    { code: "GC2-port-mismatch", contractNumber: 2, keyword: "EXPOSE", severity: "error" },
+    { code: "GC2-loopback-bind", contractNumber: 2, keyword: "0.0.0.0", severity: "error" },
+    { code: "GC4-exec-form", contractNumber: 4, keyword: "SIGTERM", severity: "error" },
+    { code: "GC4-npm-start", contractNumber: 4, keyword: "SIGTERM", severity: "error" },
+    { code: "GC7-non-root", contractNumber: 7, keyword: "non-root", severity: "warning" },
+    { code: "GC9-token-in-image", contractNumber: 9, keyword: "API token", severity: "error" },
+];
+export const CANNOT_KNOW = "What this check cannot know: whether the image is pushed to a registry Gameye can pull from, " +
+    "whether your application's port bindings in the Gameye Admin Panel match these ports and protocols, " +
+    "and whether the server binary starts, binds its ports and exits on SIGTERM. It reads only the Dockerfile " +
+    "text, not entrypoint scripts, build output or the base image's defaults. A clean result means no contract " +
+    "break was found in this text, nothing more; test the image locally before launching it.";
+const SKILL = "gameye-containerize";
+/** Split Dockerfile text into instructions, joining continuations and skipping comments and heredoc bodies. */
+export function parseDockerfile(text) {
+    const lines = text.split(/\r?\n/);
+    const escapeMatch = /^#\s*escape\s*=\s*([`\\])\s*$/i.exec(lines[0] ?? "");
+    const escape = escapeMatch ? escapeMatch[1] : "\\";
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const raw = lines[i];
+        const trimmed = raw.trim();
+        if (trimmed === "" || trimmed.startsWith("#")) {
+            i++;
+            continue;
+        }
+        const start = i + 1;
+        let joined = "";
+        let current = raw;
+        for (;;) {
+            const t = current.trimEnd();
+            if (t.endsWith(escape)) {
+                joined += t.slice(0, -1) + " ";
+                i++;
+                // Comment and empty lines inside a continuation are dropped.
+                while (i < lines.length && (lines[i].trim() === "" || lines[i].trim().startsWith("#")))
+                    i++;
+                if (i >= lines.length)
+                    break;
+                current = lines[i];
+            }
+            else {
+                joined += t;
+                i++;
+                break;
+            }
+        }
+        const m = /^\s*(\S+)\s*(.*)$/s.exec(joined);
+        if (!m)
+            continue;
+        const keyword = m[1].toUpperCase();
+        const args = m[2].trim();
+        out.push({ keyword, args, line: start });
+        // Skip heredoc bodies (RUN <<EOT ... EOT) so their lines are not read as instructions.
+        for (const h of args.matchAll(/<<(-?)\s*["']?([A-Za-z_][A-Za-z0-9_]*)["']?/g)) {
+            const [, dash, delim] = h;
+            while (i < lines.length) {
+                const l = dash ? lines[i].replace(/^\t+/, "") : lines[i];
+                i++;
+                if (l.trim() === delim)
+                    break;
+            }
+        }
+    }
+    return out;
+}
+function splitStages(instructions) {
+    const stages = [];
+    for (const ins of instructions) {
+        if (ins.keyword === "FROM") {
+            const words = ins.args.split(/\s+/).filter(Boolean);
+            let platform;
+            const rest = [];
+            for (const w of words) {
+                const p = /^--platform=(.*)$/i.exec(w);
+                if (p)
+                    platform = p[1];
+                else if (!w.startsWith("--"))
+                    rest.push(w);
+            }
+            const asIdx = rest.findIndex((w) => w.toUpperCase() === "AS");
+            stages.push({
+                from: ins,
+                image: rest[0] ?? "",
+                platform,
+                name: asIdx >= 0 ? rest[asIdx + 1]?.toLowerCase() : undefined,
+                body: [],
+            });
+        }
+        else if (stages.length > 0) {
+            stages[stages.length - 1].body.push(ins);
+        }
+    }
+    return stages;
+}
+/** The final stage plus any earlier stages it is built FROM, root first. */
+function finalChain(stages) {
+    const chain = [];
+    let idx = stages.length - 1;
+    while (idx >= 0) {
+        const stage = stages[idx];
+        chain.unshift(stage);
+        const parent = stage.image.toLowerCase();
+        idx = stages.findIndex((s, j) => j < idx && s.name === parent);
+    }
+    return chain;
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function parseExecForm(args) {
+    if (!args.startsWith("["))
+        return undefined;
+    try {
+        const parsed = JSON.parse(args);
+        return Array.isArray(parsed) && parsed.every((x) => typeof x === "string") ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse `KEY=value KEY2="v w"` (or legacy `KEY value` for ENV) into pairs. */
+function parseAssignments(keyword, args) {
+    const legacy = /^([A-Za-z_][A-Za-z0-9_]*)\s+(.*)$/s.exec(args);
+    if (keyword === "ENV" && legacy && !args.split(/\s+/)[0].includes("=")) {
+        return [{ name: legacy[1], value: unquote(legacy[2].trim()) }];
+    }
+    const pairs = [];
+    const re = /([A-Za-z_][A-Za-z0-9_]*)(?:=("(?:[^"\\]|\\.)*"|'[^']*'|\S*))?/g;
+    for (const m of args.matchAll(re))
+        pairs.push({ name: m[1], value: m[2] === undefined ? undefined : unquote(m[2]) });
+    return pairs;
+}
+function unquote(v) {
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))
+        return v.slice(1, -1);
+    return v;
+}
+const SECRET_NAME = /(TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|PRIVATE_KEY|CREDENTIAL)/i;
+const SECRET_VALUE = /^(AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_\w{20,}|sk-[A-Za-z0-9_-]{20,}|xox[abpr]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+)$/;
+function isLiteral(value) {
+    return value !== undefined && value !== "" && !/^\$\{?[A-Za-z_][A-Za-z0-9_]*(:-[^}]*)?\}?$/.test(value);
+}
+function parseExpose(args) {
+    const out = [];
+    for (const word of args.split(/\s+/).filter(Boolean)) {
+        const m = /^(\d+)(?:-(\d+))?(?:\/(tcp|udp))?$/i.exec(word);
+        if (!m)
+            continue; // variables and other forms can't be resolved statically
+        out.push({ from: Number(m[1]), to: Number(m[2] ?? m[1]), protocol: (m[3]?.toLowerCase() ?? "tcp") });
+    }
+    return out;
+}
+function rule(code) {
+    return DOCKERFILE_RULES.find((r) => r.code === code);
+}
+// ── Check ───────────────────────────────────────────────────────────────────
+export function checkDockerfile(text, opts = {}) {
+    const instructions = parseDockerfile(text);
+    const stages = splitStages(instructions);
+    if (instructions.length === 0 || stages.length === 0) {
+        throw new GuardError("No Dockerfile instructions found: pass the full Dockerfile text, starting with a FROM line.");
+    }
+    const findings = [];
+    const add = (code, line, message, fix) => findings.push({ severity: rule(code).severity, code, line, message, fix });
+    const chain = finalChain(stages);
+    const root = chain[0];
+    const finalFrom = chain[chain.length - 1].from;
+    const runtime = chain.flatMap((s) => s.body);
+    // GC1: linux/amd64 only.
+    for (const stage of chain) {
+        if (stage.platform && /arm64|aarch64|linux\/arm\b|arm\/v/i.test(stage.platform)) {
+            add("GC1-arm64-platform", stage.from.line, `The runtime image is pinned to ${stage.platform}; the Gameye fleet runs linux/amd64 only.`, `Remove the arm64 --platform pin (or use --platform=linux/amd64) and build with docker buildx build --platform=linux/amd64. See ${SKILL}.`);
+        }
+    }
+    if (/^mcr\.microsoft\.com\/windows|nanoserver|servercore/i.test(root.image) || /^windows/i.test(root.platform ?? "")) {
+        add("GC1-windows-base", root.from.line, "The runtime image uses a Windows base image; Gameye runs Linux containers only.", `Build a Linux dedicated server and use a Linux base image such as debian:bookworm-slim. See ${SKILL}.`);
+    }
+    // GC2: EXPOSE present and consistent with declared ports.
+    const exposes = runtime.filter((i) => i.keyword === "EXPOSE");
+    if (exposes.length === 0) {
+        add("GC2-expose-missing", finalFrom.line, "The runtime stage has no EXPOSE; the exposed ports must match what the server binds and the application's port bindings.", `Add EXPOSE <port>/<protocol> for every port the server binds, e.g. EXPOSE 7777/udp. See ${SKILL}.`);
+    }
+    else if (opts.ports && opts.ports.length > 0) {
+        const exposed = exposes.flatMap((i) => parseExpose(i.args).map((p) => ({ ...p, line: i.line })));
+        const lastExpose = exposes[exposes.length - 1].line;
+        const isExposed = (d) => exposed.some((e) => e.protocol === d.protocol && d.port >= e.from && d.port <= e.to);
+        for (const d of opts.ports) {
+            if (isExposed(d))
+                continue;
+            const other = exposed.find((e) => d.port >= e.from && d.port <= e.to);
+            add("GC2-port-mismatch", other?.line ?? lastExpose, other
+                ? `Port ${d.port} is declared as ${d.protocol} but exposed as ${other.protocol}.`
+                : `Declared port ${d.port}/${d.protocol} is not exposed.`, `Make EXPOSE list exactly the ports and protocols the server binds (${d.port}/${d.protocol}), and match them in the application's port bindings. See ${SKILL}.`);
+        }
+        for (const e of exposed) {
+            const declared = opts.ports.some((d) => d.port >= e.from && d.port <= e.to);
+            if (declared)
+                continue;
+            const range = e.from === e.to ? `${e.from}` : `${e.from}-${e.to}`;
+            add("GC2-port-mismatch", e.line, `Port ${range}/${e.protocol} is exposed but not among the declared ports.`, `Remove the EXPOSE for ports the server does not bind, or declare them. See ${SKILL}.`);
+        }
+    }
+    // GC2 / GC4: launch command.
+    const lastOf = (kw) => [...runtime].reverse().find((i) => i.keyword === kw);
+    const launch = [lastOf("ENTRYPOINT"), lastOf("CMD")].filter((i) => i !== undefined).sort((a, b) => a.line - b.line);
+    for (const ins of launch) {
+        const exec = parseExecForm(ins.args);
+        if (!exec) {
+            add("GC4-exec-form", ins.line, `${ins.keyword} uses shell form, so /bin/sh is PID 1 and swallows SIGTERM; the server is hard-killed with no drain.`, `Use exec form, e.g. ${ins.keyword} ["/server/game-server", "--port", "7777"], and exec the binary from any entrypoint script. See ${SKILL}.`);
+        }
+        const words = exec ?? ins.args.split(/\s+/);
+        const cmd = words.join(" ");
+        if (/(^|[\s/])(npm|yarn)(\s+run)?\s+start\b/.test(cmd)) {
+            add("GC4-npm-start", ins.line, `${ins.keyword} launches through npm/yarn start, which sits between PID 1 and the server and swallows SIGTERM.`, `Run the server directly, e.g. ${ins.keyword} ["node", "server/server.js"]. See ${SKILL}.`);
+        }
+        if (/(^|[^\d.])127\.\d{1,3}\.\d{1,3}\.\d{1,3}(?![\d.])|\blocalhost\b/i.test(cmd)) {
+            add("GC2-loopback-bind", ins.line, `${ins.keyword} binds the server to a loopback address, which is unreachable from outside the container.`, `Bind on 0.0.0.0 (all interfaces) instead of 127.0.0.1 or localhost. See ${SKILL}.`);
+        }
+    }
+    // GC7: non-root user.
+    const user = lastOf("USER");
+    const userName = user?.args.split(/\s+/)[0].split(":")[0];
+    if (!user || userName === "root" || userName === "0") {
+        add("GC7-non-root", user?.line ?? finalFrom.line, user ? "The runtime stage switches to root." : "The runtime stage sets no USER, so the server runs as root unless the base image says otherwise.", `Create a system user and switch to it before ENTRYPOINT, e.g. USER game. See ${SKILL}.`);
+    }
+    // GC9: no Gameye API token or credential in ENV/ARG (any stage; the Dockerfile itself is shared).
+    const secrets = [];
+    for (const ins of instructions) {
+        if (ins.keyword !== "ENV" && ins.keyword !== "ARG")
+            continue;
+        for (const { name, value } of parseAssignments(ins.keyword, ins.args)) {
+            const gameye = name.toUpperCase() === "GAMEYE_API_TOKEN";
+            const literal = isLiteral(value);
+            const credential = gameye || (literal && (SECRET_NAME.test(name) || SECRET_VALUE.test(value)));
+            if (!credential)
+                continue;
+            if (literal)
+                secrets.push(value);
+            add("GC9-token-in-image", ins.line, 
+            // Only the fixed GAMEYE_API_TOKEN name is echoed: any other name is user text and may itself hold a token.
+            `${ins.keyword} ${gameye ? `GAMEYE_API_TOKEN${value === undefined ? "" : `=${MASK}`}` : "on this line"} puts ${gameye ? "a Gameye API token" : "a credential"} in the image or its build history.`, `Remove it from the Dockerfile. The Gameye API token belongs to your backend only; pass only short-lived per-match values in the session env. Rotate the token if this was ever pushed. See ${SKILL}.`);
+        }
+    }
+    findings.sort((a, b) => a.line - b.line);
+    return { findings: redact(findings, secrets) };
+}
+/** Replace every flagged credential value with `***`, wherever it appears. */
+function redact(findings, secrets) {
+    const values = [...new Set(secrets)].filter((s) => s.length >= 4).sort((a, b) => b.length - a.length);
+    const clean = (t) => values.reduce((acc, v) => acc.split(v).join(MASK), t);
+    return findings.map((f) => ({ ...f, message: clean(f.message), fix: clean(f.fix) }));
+}
+export function formatDockerfileReport(result) {
+    const errors = result.findings.filter((f) => f.severity === "error").length;
+    const warnings = result.findings.length - errors;
+    const lines = [`Dockerfile check against the ${SKILL} container contract: ${errors} error(s), ${warnings} warning(s).`, ""];
+    if (result.findings.length === 0) {
+        lines.push("No contract issues found in the Dockerfile text.", "");
+    }
+    for (const f of result.findings) {
+        lines.push(`${f.severity.toUpperCase()} ${f.code} (line ${f.line}): ${f.message}`, `  Fix: ${f.fix}`, "");
+    }
+    lines.push(CANNOT_KNOW);
+    return lines.join("\n");
+}

package/dist/env.d.ts

@@ -12,19 +12,39 @@ export interface ResolvedConfig {
     baseUrl: string;
     /** Hostname only, for display. */
     host: string;
-    /** API token. Never print or return this. */
-    token: string;
+    /** API token, absent in no-token mode. Never print or return this. */
+    token?: string;
+    /** True when a usable token is configured. Derived from `token`; safe to show. */
+    hasToken: boolean;
     /** Default per-request timeout in milliseconds (GAMEYE_TIMEOUT_MS, default 30s). */
     timeoutMs: number;
+    /** Local launch and stop limits (GAMEYE_MAX_SESSIONS, GAMEYE_MAX_TTL, GAMEYE_MAX_LAUNCHES, GAMEYE_STOP_OWN_ONLY). */
+    limits: SessionLimits;
 }
+/** Limits on what an agent can start through one server process. See limits.ts. */
+export interface SessionLimits {
+    /** Sessions started by this process that may run at once. */
+    maxSessions: number;
+    /** Longest TTL a launch may ask for, as given (e.g. `4h`). */
+    maxTtl: string;
+    maxTtlMs: number;
+    /** Launches per server process. */
+    maxLaunches: number;
+    /** Stop only sessions this process started. */
+    stopOwnOnly: boolean;
+}
+export declare const DEFAULT_LIMITS: SessionLimits;
 /** Per-request timeout used when GAMEYE_TIMEOUT_MS is not set. */
 export declare const DEFAULT_TIMEOUT_MS = 30000;
 export declare class ConfigError extends Error {
     constructor(message: string);
 }
+/** The one stderr line printed at start in no-token mode. Never mentions a token value. */
+export declare const NO_TOKEN_NOTICE = "No GAMEYE_API_TOKEN set: account tools will refuse until a token is set and the server is restarted.";
 /**
  * Resolve the server configuration from an environment object.
  * Pure: throws ConfigError on any invalid combination and never touches process state.
+ * A missing token is not an error: it resolves with `hasToken: false`.
  */
 export declare function resolveConfig(env: Record<string, string | undefined>): ResolvedConfig;
 /** Resolve from process.env, printing a clear message and exiting 1 on any error. */
@@ -33,4 +53,5 @@ export declare function loadConfigOrExit(env?: Record<string, string | undefined
 export declare function resultPrefix(config: {
     environment: EnvironmentLabel;
     host: string;
+    hasToken?: boolean;
 }): string;