hoi4-agent-tools 0.0.0-bootstrap.1 → 0.1.3

package/docs/adr/0011-http-security.md

@@ -0,0 +1,16 @@
+# ADR 0011: Authenticated, origin-checked Streamable HTTP
+
+- Status: accepted
+- Date: 2026-07-10
+
+## Decision
+
+HTTP binds to `127.0.0.1` by default. Every request is authenticated. Loopback deployments may use long static bearer tokens loaded from environment variables. Non-loopback deployment requires an HTTPS public resource URL and JWT verification against configured OAuth/OIDC issuer, JWKS, audience, algorithms, expiry, and scopes. Protected-resource metadata is published and linked from Bearer challenges. Write-scoped tool calls are rejected at the transport with an MCP 2025-11-25 step-up challenge while the corresponding handlers independently enforce the same scope. Present origins are allowlisted, Host is validated, sessions use cryptographically secure IDs bound to principals, clients, and a monotonic scope set, and body/rate/concurrency/session limits are enforced.
+
+## Rationale
+
+MCP sessions are routing state, not authentication. OAuth resource-server validation and principal-to-workspace grants prevent token passthrough, confused-deputy behavior, and cross-user workspace access. Origin and Host checks address DNS rebinding and browser-origin attacks.
+
+## Consequences
+
+The server does not implement an authorization server. Operators configure a compatible issuer or keep HTTP on loopback. Stdio does not use MCP OAuth and inherits local process permissions plus the same workspace policy.

package/docs/adr/README.md

@@ -0,0 +1,13 @@
+# Architecture decisions
+
+1. [Runtime and language](0001-runtime-and-language.md)
+2. [Lossless source model](0002-lossless-source-model.md)
+3. [Image and font codecs](0003-image-and-font-codecs.md)
+4. [Focus layout](0004-focus-layout.md)
+5. [Offline rendering](0005-offline-rendering.md)
+6. [MCP SDK and protocol](0006-mcp-sdk-and-protocol.md)
+7. [Storage and transactions](0007-storage-and-transactions.md)
+8. [Test strategy](0008-test-strategy.md)
+9. [Packaging and Registry](0009-packaging-and-registry.md)
+10. [Unsupported/refusal policy](0010-unsupported-and-refusal-policy.md)
+11. [HTTP security](0011-http-security.md)

package/docs/architecture.md

@@ -0,0 +1,60 @@
+# Architecture
+
+All external behavior enters through MCP and calls typed domain services. Transport code validates protocol and authorization; it does not parse source, lay out graphs, render images, or write files.
+
+In this documentation, “read-only” scan, lint, layout, and render operations mean that registered HOI4 source bytes are never changed. MCP `readOnlyHint` follows the protocol's broader environmental-mutation meaning: an operation that creates content-addressed evidence under an allowlisted generated-artifact root advertises `readOnlyHint: false`, even though it cannot edit game or mod source.
+
+```text
+MCP tools/resources/prompts
+          │
+          ▼
+focus / gui / map services
+          │
+          ▼
+workspace resolver ─ source CST ─ symbol/reference index
+          │                 │
+          ├─ diagnostics ───┤
+          ├─ artifact store ┤
+          └─ transaction journal / diffs / rollback
+```
+
+## Workspace overlay
+
+A workspace combines a mod root, an optional installed-game reference root, ordered dependency roots, owner-scoped `replace_path` declarations, conventional subsystem roots, an artifact root, cache root, and optional fixture root. File traversal is stable. Same-relative-path files are shadowed by higher load order; each mod or dependency replacement declaration hides its subtree only in lower-precedence roots.
+
+Paths are canonicalized through existing ancestors. Public operations accept relative paths only and reject traversal, absolute/device/UNC paths, alternate data streams, Windows device names, and symlink or junction escapes. Game and dependency roots are immutable.
+
+## Source model
+
+The lexer retains original bytes and every token: whitespace, comments, strings, atoms, operators, braces, and invalid ranges. The CST retains duplicate keys and ordered blocks. Semantic readers build focus, GUI, or map views over CST ranges. Targeted replacements splice the original decoded text and encode with the original UTF-8 BOM, UTF-8, or Windows-1252 mode. No-change serialization returns original bytes.
+
+Malformed or unrepresentable content blocks rewriting. Unknown constructs remain raw source, not guessed fields.
+
+## Shared index
+
+`CoreEngine.scan` creates the authoritative `SymbolIndex` for an exact file snapshot. Focus consumes it directly; Scripted GUI receives that same index when building its connected source graph; Agent Nudger attaches it as `MapWorkspaceIndex.sharedIndex` and layers raster/network semantics over it. Proposed-file graphs rebuild through the shared index service rather than a domain parser authority.
+
+The index connects tree/focus IDs, sprites/textures, GUI elements, scripted GUI entries, localisation, state/province IDs and colors, strategic regions, adjacencies, supply nodes, railways, and cross-file references. Definitions retain load order, locations, collision state, and override evidence. Province definitions are resolved from each source root's own `default.map` selector, with lower partial roots inheriting the active selector name.
+
+Large binary rasters and translation catalogs are selected lazily rather than retained wholesale. Agent Nudger follows the active `default.map` province-bitmap selector. The shared index uses `l_english`, while GUI scenario operations add every explicitly requested language. This narrows scan breadth without changing source precedence or the lossless representation of any selected file.
+
+## Determinism
+
+Canonical JSON sorts keys with a locale-independent total UTF-16 code-unit order, traversal uses stable path ordering, layout tie-breaking is fixed, and artifact names are content hashes. Render profiles include source/asset/font hashes and all scenario geometry. Timestamps, host paths, locale collation, random IDs, and time zones are excluded from hashed artifacts.
+
+## Artifacts and transactions
+
+Generated evidence is content-addressed below `.hoi4-agent/artifacts`. Artifact manifests bind their
+immutable provenance address to a hash-only canonical workspace and configured/runtime owner
+identity. Runtime-generated stores also carry an atomic persistent owner claim, while statically
+configured workspaces retain one shared operator identity for their explicit grants.
+
+A transaction includes the complete affected-file set, before/after hashes and blobs, operation
+provenance, validation, source/binary/visual diffs, expiry, principal, workspace/root fingerprint,
+and plan hash. Its complete mutable journal is HMAC-authenticated by a random key beneath the
+isolated `serverStateRoot`; a protected latest-revision head prevents replay and bounds state to one
+head per admitted cache journal.
+
+Apply acquires one workspace write lock, rechecks preconditions, stages files on the same volume, journals deterministic replacements, rebuilds the affected index, and post-validates. Failure and startup recovery restore original blobs. This is recoverable logical atomicity; another process can briefly observe a replacement sequence.
+
+Detailed decisions are recorded in [ADRs](adr/README.md).

package/docs/artifacts.md

@@ -0,0 +1,133 @@
+# Artifact resources
+
+Tools return compact summaries and links. Content is stored by SHA-256 under the workspace's configured artifact root and exposed through an authorization-checked URI:
+
+```text
+hoi4-agent://workspace/{workspaceId}/artifact/{sha256}/{provenanceHash}/{name}
+```
+
+Each version-2 manifest records name, MIME type, byte size, content hash, artifact kind,
+tool/schema version, SHA-256 source hashes, render profile, domain metadata, and hash-only bindings
+for the resolved workspace and its configured or runtime owner. Filesystem paths and raw principals
+are not exposed. Missing/create/delete states belong in provenance metadata, never sentinel values
+inside the source-hash map.
+
+Very broad domain inventories retain a deterministic path/hash sample capped at 256 entries and
+128 KiB in the manifest, plus a count and a SHA-256 commitment over every length-prefixed sorted
+path/hash pair. This policy applies uniformly to project, focus, GUI, and map evidence. Complete
+inventories remain in the structured artifact content: project diagnostics use their exact `files`
+inventory, while focus, GUI, and map JSON evidence records exact source hashes. Binary and HTML
+review artifacts carry the same bounded, digest-backed provenance and are paired with the exact
+structured evidence for their bundle. Bounding a manifest therefore does not drop source evidence.
+The inventory commitment uses the versioned `sha256-length-prefixed-path-digest-v1` algorithm
+recorded in metadata.
+
+The manifest is immutable for a given content hash, provenance hash, and artifact name. Repeating the same bytes, name, and provenance is idempotent. Identical content produced from a different source revision receives a distinct provenance hash and URI while reusing the same content-addressed bytes, so earlier evidence is never rewritten or ambiguously relabelled.
+
+Artifact names ending in `.manifest.json`, under an ASCII case-insensitive comparison, are reserved
+for store metadata and rejected. This rule is identical on case-sensitive and case-insensitive
+filesystems, so content can never be mistaken for an inventory manifest.
+
+The workspace and owner bindings participate in the provenance hash and are checked by list,
+describe, and resource reads. A store reused by another workspace ID, canonical root topology, or
+runtime principal cannot enumerate or read the older manifests. Statically configured workspaces
+derive one shared operator identity, so all explicitly granted principals retain their intended
+access. Legacy unbound manifests and malformed/conflicting manifests fail closed; the server does
+not delete or relabel them automatically.
+
+Resource reads are limited to 1 MiB per request and support `offset` and `length` query parameters for large artifacts. Integrity verification streams the complete artifact through a fixed-size hash buffer while retaining only the requested range, so chunking also bounds payload memory. Only a complete payload that round-trips as strict UTF-8 may return MCP `text`. Every partial range, invalid UTF-8 payload, image, and other binary returns an MCP base64 `blob`, preserving exact bytes even when a range splits a code point. Clients advance `offset` by the decoded byte count and continue until a chunk is shorter than the requested length; the same rule applies to provenance-manifest resources.
+
+Some complete logical evidence, notably an installed workspace's GUI source graph, can legitimately
+be larger than `artifactMaxSingleBytes`. Callers that opt into byte-exact logical storage receive a
+normal artifact when the payload fits. An oversized payload instead returns one small canonical
+JSON index named `*.chunks.json`. The index records `type = hoi4-agent.chunked-artifact`, the
+original name, MIME type, size, SHA-256 and description, followed by ordered chunk resource links
+with indexes, byte offsets, lengths and SHA-256 hashes. Chunks use
+`application/octet-stream`; concatenating their decoded bytes in index order must reproduce the
+recorded original size and SHA-256 exactly. The index itself is limited to 1 MiB so an MCP client
+can read it in one request.
+
+The chunks and index are one atomic artifact batch. Every physical object and provenance manifest
+counts against the same aggregate-byte and entry quotas, every chunk remains at or below the
+configured per-object ceiling, and any admission, write, cancellation or owning-commit failure
+removes all files newly created by the bundle. This representation is lossless storage, not graph
+truncation or a quota bypass. `hoi4.gui_scan` and GUI render source-graph evidence return only the
+logical index link; agents follow its resource links when they need the full graph.
+
+Logical chunk preparation has a separate fixed 536,870,912-byte in-memory batch ceiling, and a
+lower configured `artifactMaxBytes` always wins. Before any payload is copied or hashed, admission
+validates every logical write's name, provenance and byte length, checks safe aggregate arithmetic,
+and projects the complete physical entry count after chunking. Preflight yields after each 256
+logical writes so cancellation can stop a broad batch before preparation. Preparation is then
+sequential, verifies that each admitted byte length is unchanged, and yields during hashing every
+16 MiB. Chunks share the one owned logical buffer during preparation instead of duplicating it.
+Crossing the fixed preparation ceiling fails with `ARTIFACT_LOGICAL_BATCH_LIMIT` before allocation.
+
+Artifact listing is paged at no more than 100 links. The store walks the complete sorted manifest
+inventory to verify bindings and compute an exact SHA-256 inventory revision, but retains only the
+requested page in memory. Cursors name the last public URI and are accepted only when that exact URI
+still occurs under the same revision. Listing and content verification honor request cancellation
+between directories, manifests, and hash chunks.
+
+Manifest reads stat the file and enforce the fixed 1 MiB ceiling before signal-aware JSON loading.
+Artifact writes, existing-content verification, quota walks, and queue waits also honor
+cancellation. A cancelled batch completes non-cancellable cleanup of every partial file. Once the
+caller's commit callback begins, that callback owns its critical-phase completion rules.
+
+## Storage placement
+
+A mod workspace defaults to `<mod>/.hoi4-agent/artifacts`; any in-mod override must remain beneath
+that exact generated subtree. An operator may instead place it beneath a configured `storageRoots`
+parent. A primary `game` or `dependency` workspace must always use an explicit operator-owned
+artifact root beneath `storageRoots`, separate from its explicit cache root. Artifact and cache
+roots cannot overlap each other or a source root.
+
+Generated artifact writes never make the game, dependency, or fixture source writable. Source
+changes are a separate transaction surface and are confined to the mod root.
+
+## Retention quotas
+
+The default per-workspace limits are:
+
+- `artifactMaxBytes`: 536,870,912 bytes across content and manifests;
+- `artifactMaxEntries`: 5,000 provenance manifests;
+- `artifactMaxSingleBytes`: 134,217,728 bytes for one content object;
+- serialized provenance manifests have a separate fixed 1 MiB ceiling and bounded fields.
+- one logical chunk-preparation batch has a fixed 536,870,912-byte ceiling.
+
+Content deduplication means a reused content hash adds no duplicate content bytes, while a new
+provenance manifest still counts as an entry and consumes its serialized bytes. Within one server
+process, the store measures current usage under an in-process per-root write queue before adding
+immutable files. Multi-artifact operations preflight all logical writes and their projected
+normal/chunk/index entries as one batch before payload copying or hashing, then retain newly created
+content and manifests only if their owning operation commits. A failed transaction-journal
+admission removes the diff files created by that batch without deleting pre-existing shared
+content or provenance. If the complete content and manifest would exceed a count, aggregate-byte,
+or per-object ceiling, the store refuses the write with `ARTIFACT_STORAGE_LIMIT`,
+`ARTIFACT_LOGICAL_BATCH_LIMIT`, `ARTIFACT_SINGLE_LIMIT`, `ARTIFACT_CHUNK_INDEX_LIMIT`, or
+`ARTIFACT_MANIFEST_LIMIT`; it does not write a truncated artifact or evict older evidence. Listing
+also refuses when an externally modified store is already over its configured retention budget.
+
+Artifact retention has no automatic garbage collector. Operator deletion is explicit and should
+be coordinated with active requests; deleting an artifact invalidates its URI. In contrast,
+transaction-journal cleanup follows the separate rules in [transactions](transactions.md). Do not
+share one writable artifact root between uncoordinated server processes; an operating-system
+storage service or operator must provide that coordination.
+
+Typical artifacts:
+
+- shared diagnostics and capability reports;
+- focus HTML/SVG/PNG/JSON, generated-source maps, and hash-bound planning sidecars;
+- GUI renders, galleries, hierarchy/click maps, comparisons, and fidelity reports;
+- map layers, changed-pixel reports, and before/after previews;
+- transaction manifests, source diffs, binary diffs, and validation reports.
+
+Structured JSON evidence records source paths, hashes, frame numbers, dimensions, formats, and
+fidelity metadata, but strips embedded `data:` payloads and glyph bitmap bytes. Composite SVG and
+PNG review renders may contain processed, source-derived icon, sprite-frame, or font-glyph pixels
+needed to inspect the requested interface; they are principal-bound generated evidence, not raw
+asset-file resources. The server never registers an installed-game, dependency, or mod raster/font
+file itself as an artifact.
+
+Artifacts are evidence. External HOI4 source remains authoritative. Deleting the configured
+artifact root invalidates only generated evidence, not mod content.

package/docs/compatibility.md

@@ -0,0 +1,33 @@
+# Compatibility and versioning
+
+## Runtime and platforms
+
+| Component | Supported                                                                                                                                         |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Node.js   | 22.x and 24.x                                                                                                                                     |
+| Windows   | Windows 10/11 x64                                                                                                                                 |
+| Linux     | Current x64/arm64 distributions supported by Node and Sharp                                                                                       |
+| macOS     | Source package supported; CI coverage may lag Windows/Linux                                                                                       |
+| MCP       | Final `2025-11-25` only; initialization requests for other revisions receive `2025-11-25` so clients without that revision can disconnect cleanly |
+| HOI4      | Current file formats are capability-scanned; no fixed game installation path                                                                      |
+
+The `2026-07-28` protocol was a release candidate at 0.1.0 development time. Adopting its breaking stateless core and SDK v2 requires a compatibility release after it is final and supported by clients.
+
+The pinned SDK also recognizes `2025-06-18`, `2025-03-26`, `2024-11-05`, and `2024-10-07`, but this server does not claim them: its public contracts use the final revision's structured output and resource-link behavior. Both stdio and Streamable HTTP gate negotiation to `2025-11-25`. After initialization, every Streamable HTTP POST, GET, or DELETE must carry `MCP-Protocol-Version: 2025-11-25`; a missing or different value receives a JSON-RPC error with HTTP status 400.
+
+## Public schemas
+
+Tool names and input/output schemas are public API. Additive compatible changes use a minor release. Removing/renaming a tool or changing accepted/returned meaning requires a major release or a documented deprecation period. Schema version, package version, server implementation version, changelog, container tag, and Registry metadata stay synchronized.
+
+Focus consumers can use `focus-plan.schema.json`, `focus-planning-sidecar.schema.json`, and `continuous-focus-palette.schema.json`. The planning sidecar is hash-bound enrichment data; it is not Clausewitz source and is never loaded by HOI4.
+
+Focus reward import ships a reviewed native-effect identifier catalog derived from the official
+HOI4 1.19.2 `effects_documentation.md`. This lets the importer distinguish engine effects from
+direct `scripted_effect_id = yes/{ ... }` calls without requiring an installed game at runtime.
+Compatibility reviews must refresh the catalog when official effect identifiers change; unknown
+effect-position scalars remain source-linked helper references so stale or misspelled calls lint
+as missing instead of disappearing.
+
+## Configuration migration
+
+Config has an integer `version`. Unknown versions or fields fail with deterministic diagnostics. A future migration utility must print a reviewable proposed config and never edit a client or workspace silently.

package/docs/completion-report.md

@@ -0,0 +1,69 @@
+# Completion report: 0.1.3 release candidate
+
+- Candidate version: `0.1.3`
+- Report date: 2026-07-11
+- Status: fix-forward implementation in qualification; public delivery incomplete
+
+## Implemented scope
+
+The release candidate provides the shared source-preserving core, Focus Tree Workbench, Scripted GUI Studio, Agent Nudger map workflow, read-only-by-default transaction controls, stdio and authenticated Streamable HTTP transports, package entry points, schemas, synthetic portable fixtures, and public deployment documentation described by this repository.
+
+The npm payload is explicitly limited to compiled entry points, documentation, schemas, `server.json`, and the project license, security policy, README, and changelog. Installed-game data, third-party mod data, fixtures, tests, source files, local configuration, and workspace artifacts are excluded.
+
+## Qualification evidence
+
+The candidate has passed all 46 portable test files: 495 tests passed and one POSIX case was intentionally skipped on Windows. The latest enforced coverage is 88.44% statements, 78.25% branches, 91.28% functions, and 89.90% lines.
+
+Release-specific qualification also covers:
+
+- installation of the actual `npm pack` tarball into an isolated consumer, including an empty-cache install that proves `--prefer-offline` can fetch missing dependencies;
+- execution of the installed stdio, HTTP, and setup entry points;
+- package-content allowlisting, workspace-path leak checks, synchronized package and Registry metadata, and generated-schema checks;
+- npm dependency audit, registry signatures, and attestations;
+- live validation against the official MCP Registry API and pinned schema;
+- official MCP Inspector discovery against the production stdio entry point;
+- a production Docker build and protocol-only container stdio initialization/discovery; the release workflow records the final non-self-referential image digest in `container-image.json` rather than embedding an obsolete candidate digest into documentation copied inside that image;
+- immutable GitHub Action references, workflow and shell linting, strict release ordering, and byte-for-byte npm/GitHub release verification;
+- pinned Dockerfile-frontend and Node base-image digests, a multi-platform base supporting `linux/amd64` and `linux/arm64`, and a warning-free Docker build check;
+- read-only production-container checks proving OAuth metadata discovery, unauthenticated `401`, invalid-Origin `403`, protocol-only stdio initialization/discovery of all 26 tools, and a real read-only `hoi4.project_status` call from the non-root Node 22.23.1 runtime;
+- reusable bounded GUI helper templates, source-valid typed helper output, explicit state variants, deterministic scrolling and static meter handoffs, and refusal tests for unsafe or ambiguous helper compilation;
+- explicit even-odd province polygons with raster-boundary bounds checking before rasterization, pixel-center sampling, and refusal rather than clipping;
+- interrupted GitHub release recovery through a uniquely selected, byte-verified draft without asset overwrite or deletion, followed by exact immutable-release verification;
+- three installed-data qualifications covering a large vanilla/external focus workflow, a real GUI/GFX/font graph with deterministic full/annotated renders, and full province-map scan/render/storage without launching the game; the 302,497,021-byte canonical GUI graph was stored exactly as three bounded resources plus its one-read index while the default 128 MiB per-object ceiling remained enabled;
+- deterministic cold/warm benchmark output for the 255-focus, 203-visible-element GUI, and all-layer map workloads, including same-size/same-mtime content-hash invalidation.
+
+Known refusal cases and intentional boundaries remain documented in [Known limitations](limitations.md). They are explicit product constraints, not fallback implementations.
+
+## Public delivery status
+
+The immutable `v0.1.2` release attempt published npm with trusted-publisher provenance and then
+stopped in independent verification because the pinned npm subprocess reported the configured
+official Registry URL without a trailing slash while the strict verifier required the canonical
+slash-terminated spelling. npm's signature audit itself verified 448 registry signatures and 128
+attestations. The workflow correctly skipped GHCR, GitHub Release, MCP Registry, and final public
+verification. The public npm `0.1.2` bytes and tag are retained as immutable audit evidence.
+
+No complete multi-surface public release is claimed in this report. The following evidence remains
+pending until the `0.1.3` fix-forward workflow finishes:
+
+| Surface        | Required completion evidence                                                                              | Status       |
+| -------------- | --------------------------------------------------------------------------------------------------------- | ------------ |
+| GitHub source  | Public canonical repository containing the tested commit and immutable `v0.1.3` tag                       | Pending      |
+| npm            | Public `hoi4-agent-tools@0.1.3` with exact tarball integrity and SLSA provenance                          | `0.1.2` only |
+| GitHub release | Immutable `v0.1.3` release containing the exact npm and container digest manifests                        | Pending      |
+| GHCR           | Public anonymous `0.1.3` digest with two runtime platforms and source-bound SBOM/provenance subjects      | Pending      |
+| MCP Registry   | Exact `io.github.klimPaskov/hoi4-agent-tools@0.1.3` metadata with official `active` and `isLatest` status | Pending      |
+| Public install | Clean registry installation, signature audit, MCP initialization, and tool discovery                      | Pending      |
+
+## First-release completion sequence
+
+1. Commit the tested candidate on `main` and push it to the canonical public repository.
+2. Run the manual GHCR bootstrap workflow, make the new package public in GitHub, and verify the bootstrap index without saved credentials.
+3. Create `npm-bootstrap-v0.0.0-bootstrap.1`, store a shortest-lived npm granular token only as `NPM_BOOTSTRAP_TOKEN`, and run the manual non-OIDC npm bootstrap workflow from that tag. The earlier immutable `.0` attempt stopped before publication; it is retained as audit evidence rather than rewritten.
+4. Revoke and delete `NPM_BOOTSTRAP_TOKEN`, then configure npm trusted publishing for `klimPaskov/hoi4-agent-tools`, `release.yml`, and the explicit `npm publish` allowed action.
+5. Preserve `v0.1.0` and `v0.1.1`, plus the immutable `v0.1.2` tag and public npm package whose independent verification stopped before any downstream writer. Do not create `NPM_TOKEN`; the OIDC workflow rejects it.
+6. Qualify the synchronized `0.1.3` fix-forward commit, including the shared canonical npm Registry constant and strict refusal coverage, then create `v0.1.3` only from an exact green commit.
+7. Allow the release workflow to publish and verify npm, digest-immutable GHCR, the immutable GitHub release, and MCP Registry in its enforced order.
+8. Update this report with the commit, workflow run, public URLs, npm and image digests, and Registry status. Only then is public delivery complete.
+
+Detailed commands and failure behavior are documented in [Release and MCP Registry publication](release.md).