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

package/docs/testing.md

@@ -0,0 +1,43 @@
+# Testing and fixtures
+
+```bash
+npm ci
+npm run test
+npm run test:coverage
+npm run fixtures:check
+npm run build
+npm run inspector
+npm run check
+```
+
+## Portable CI
+
+CI owns all inputs:
+
+- a 255-focus workspace with ten route families, exclusions, convergence, planner-sidecar hidden/crisis/shared-support metadata, relative/pinned/automatic positions, a real `continuous_focus_palette`, active localisation, a two-frame sprite texture, and resolved synthetic references;
+- a 170-element five-tab GUI with a dynamic list, target cards, meters, distinct frame animation, modal, all required states, licensed fixture font, and defect variants;
+- a nontrivial 24-bit BMP mini-world with islands, exact split masks/polygons, state/region/network/adjacency data, and invalid variants.
+
+Suites cover parser byte round trips, encodings, property cases, source locations, overlay/load order, custom focus roots, exact referenced-texture scanning, strict schemas, deterministic goldens, generated-source maps, planning-sidecar enrichment, image comparisons, font metrics, bitmap diffs, transaction fault/recovery, path security, cross-workspace isolation, stdio, Streamable HTTP, auth/origin/session limits, resource/prompt/tool discovery, package installation, Registry schema, and end-to-end agent workflows.
+
+## Local integration
+
+Set paths explicitly; tests are read-only:
+
+```bash
+HOI4_GAME_ROOT=/path/to/game \
+HOI4_EXTERNAL_MOD_ROOT=/path/to/mod \
+npm run test:local
+```
+
+Optionally set `HOI4_DEPENDENCY_ROOTS` to dependency roots separated by the operating system path delimiter (`;` on Windows, `:` on POSIX).
+
+Three local tests parse and deterministically render a large vanilla focus tree, build and render a current GUI/GFX/font source graph, and scan/render/store the current province map with state, coastline, supply-node, and railway data against one external mod. Generated caches and artifacts stay in a temporary directory that is removed after the suite; the external roots remain read-only, no files are copied into the repository, and the game is never launched.
+
+`npm run test:local` uses a project-owned validation runner around the standalone local Vitest configuration. It routes only `tests/local`, preserves ordinary Vitest failure codes, and independently requires the exact focus, GUI, and map qualification workflows to finish. The command fails when paths are absent and the tests skip, when a required workflow is not collected, when a worker terminates or runs out of memory, when Vitest reports any unhandled error, or when the reporter lifecycle is incomplete. A zero Vitest exit code alone is therefore not treated as success.
+
+## Performance
+
+Run the explicit, non-CI benchmark with `npm run benchmark`. It records cold/warm shared scans, the 255-node focus layout/render, the 150+ element GUI state gallery, and a full cross-root synthetic map scan plus all base-layer renders. Cache keys include content hashes; a deterministic unit test mutates content while preserving size and modification time to prove safe invalidation.
+
+Current measurements, methodology, and rerun instructions are in [performance.md](performance.md).

package/docs/third-party-notices.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+## Roboto
+
+HOI4 Agent Tools depends on `@fontsource-variable/roboto` version 5.2.10 for deterministic, host-independent artifact labels and the project-owned synthetic BMFont fixture.
+
+Copyright 2011 The Roboto Project Authors (<https://github.com/googlefonts/roboto-classic>). Roboto-Italic[wdth,wght].ttf: Copyright 2011 The Roboto Project Authors (<https://github.com/googlefonts/roboto-classic>).
+
+Roboto is licensed under the SIL Open Font License, Version 1.1 (`OFL-1.1`). The complete license text is distributed as `LICENSE` in the installed `@fontsource-variable/roboto` package. The font package is pinned in `package.json` and `package-lock.json`; generated SVG/PNG documents may contain derived glyph outlines or pixels as permitted by the OFL.
+
+The application source remains licensed under Apache-2.0 as stated in the repository [LICENSE](../LICENSE). Third-party components retain their respective licenses.

package/docs/transactions.md

@@ -0,0 +1,162 @@
+# Transactions, diffs, and rollback
+
+## Plan
+
+A domain `plan_changes`/`map_plan` call calculates every affected source and binary file before writing. Proposed bytes are validated in memory. The plan persists content-addressed before/after blobs and produces source, binary, pixel, and rendered comparison artifacts where applicable.
+
+Every proposed source target is resolved with write access restricted to the workspace's canonical
+mod root. Transaction calls cannot write the game, a dependency, a fixture, artifact storage,
+cache storage, or the reserved `.hoi4-agent` subtree as mod source.
+
+The transaction API requires both validation phases: planning must return at least one explicit in-memory check, and apply must return at least one explicit post-write check. Missing or empty callbacks fail with `TRANSACTION_DRY_RUN_VALIDATION_REQUIRED` or `TRANSACTION_POST_VALIDATION_REQUIRED`; callers cannot opt out through the typed core API. Diff artifacts are committed as one batch with the journal only after the planning validator returns structurally valid results. A rejected validator or journal admission leaves artifact inventory unchanged. A completed dry run whose explicit checks fail remains reviewable as a blocked plan and cannot be applied.
+
+Text diffs use an exact deterministic algorithm with a fixed memory bound and cancellation checks. If an exact diff would exceed the bound, planning stops with `DIFF_COMPLEXITY_LIMIT`; the server does not substitute a truncated, approximate, or misleading diff.
+
+The returned transaction ID is not approval. Review:
+
+- operations and unresolved choices;
+- affected file list;
+- source and visual diff resources;
+- diagnostic locations and validation gates;
+- expiry and plan hash.
+
+Plan and mutation tool results keep only a bounded path sample plus the authenticated transaction
+manifest resource. Review artifacts remain listed in that manifest rather than being duplicated as
+hundreds of inline resource links. `hoi4.transaction_diff` returns at most 20 files, operation
+summaries, and artifact links per page; follow every `nextCursor` until it is absent. Cursors are
+bound to the immutable plan hash and fail if reused for a different transaction. Inline validation
+contains at most five checks with an explicit truncation diagnostic; the manifest is the complete
+validation record.
+
+Focus plans include both the edited Clausewitz source and its adjacent `.focus-plan.json` design sidecar in one transaction. The manifest also retains the proposed generated-source map and sidecar artifacts through apply and rollback so each generated focus range remains traceable to its planning/source node.
+
+## Apply
+
+Call `hoi4.transaction_apply` separately with `workspaceId`, `transactionId`, and the exact 64-character `expectedPlanHash`. The server rejects a different principal/workspace, changed roots, failed dry run, expiry, reused state, or any changed before-hash.
+
+The persisted immutable plan payload is recomputed against `planHash` whenever a manifest is
+loaded. A recomputable integrity hash remains useful for deterministic diagnostics, but is never an
+authorization boundary. Every exact-version manifest also carries an HMAC-SHA-256 tag over the
+complete canonical payload except that tag itself, including expiry, state, applied files, failure,
+rollback status, operations, plan, diagnostics, and validation. The random 256-bit key is created
+atomically beneath the non-overlapping operator `serverStateRoot`; it is never derived from public
+workspace data or exposed through MCP.
+
+The same protected state stores one authenticated latest-revision head per admitted journal. An
+older valid manifest is rejected as replay. Manifest replacement is cache-first and caller state is
+updated only after persistence: a crash between cache replacement and protected-head commit may
+reconcile only an HMAC-valid exact `+1` successor. Missing heads, gaps, conflicting same revisions,
+and forged successors fail closed. Successor creation is durable before older revision-head files
+are removed, so an old-head cleanup failure does not break loading.
+
+Ordinary status, diff, and resource reads are pure: they accept only an exact protected head and
+never promote state. An authenticated cache-first exact successor reports
+`TRANSACTION_HEAD_RECONCILIATION_REQUIRED` until startup recovery or an authorized write path
+performs the narrowly allowed reconciliation.
+
+Unauthenticated journals from an older deployment are deliberately not auto-migrated. They remain
+fail-closed for operator review because no server-held secret can prove their origin. Archive or
+remove them explicitly before reclaiming their quota; do not manufacture an authentication tag.
+
+During apply the server:
+
+1. takes the exclusive workspace lock;
+2. rechecks every precondition;
+3. writes and flushes same-volume staged files;
+4. journals backups and replacements in deterministic order;
+5. rebuilds the shared index;
+6. runs post-write validation;
+7. removes temporary backups only after success.
+
+The workspace lock serializes cooperating server processes that use the same cache. Before each
+replacement, the current source hash is checked again; after post-write validation, every result
+hash is checked. These checks detect stale ordinary edits, but they are not a race-proof
+filesystem sandbox against a hostile operating-system principal.
+
+## Failure and recovery
+
+Any error starts rollback in reverse file order. Existing backups or persisted blobs restore exact original bytes, including BMP headers and padding. Restores stage and flush bytes before atomically renaming over the current target; they never unlink an existing target before a blob replacement. A durable `rolling_back` journal can also resume the legacy interrupted state where that target is already missing, but only after verifying its persisted before-blob. Startup scans unfinished journals and completes rollback before accepting a new write.
+
+Runtime registration definitions are not persisted, but their hash-only ownership claims are.
+Their unfinished journals are recovered only after the same principal re-registers an exactly
+matching canonical workspace and the persistent claim is verified, before status or write access
+is returned to the caller.
+
+Lock owners record the host, process, server instance, and process start time. A dead owner on the same host is cleared during startup recovery; an ownerless acquisition lock is cleared only after a 30-second grace period. A live local owner and every different- or unknown-host owner remain authoritative. Automatic cross-host crash recovery is intentionally unsupported: deployments sharing a workspace/cache filesystem across hosts must provide single-writer orchestration and operator-confirmed recovery rather than relying on local PID evidence.
+
+Multi-file atomicity is logical and recoverable, not an operating-system transaction. External
+processes can briefly observe replacement steps. Under an operator-controlled filesystem, success
+is returned only after post-write validation and final result-hash verification. A principal able
+to concurrently replace directories, links, mounts, or files outside the transaction lock already
+has direct filesystem authority and is outside the application security boundary; the server does
+not claim race-proof atomicity against that actor.
+
+## Journal retention and quotas
+
+Transaction journals live under `<cacheRoot>/transactions`. The configurable defaults are 128
+journals and 536,870,912 bytes per workspace cache. A plan must also fit its own rollback blobs,
+serialized manifest, and replacement-work estimate beneath the byte ceiling. The plan is refused
+with `TRANSACTION_JOURNAL_LIMIT` before a usable journal is committed if either the count, stored
+bytes, or single-plan work budget would be exceeded. No smaller or truncated rollback journal is
+substituted.
+
+One manifest is bounded to 1,000 changed files, 1,000 operations, 10,000 read dependencies, 100
+validation checks, 100 diagnostics, 512 artifacts, and 1,000 applied-file entries. Inputs over a
+count limit or the existing serialized journal/work-byte budget are rejected, never truncated.
+Post-write validation is preflighted against the combined check and diagnostic counts before the
+manifest is mutated. A 100+1 overflow triggers exact rollback while preserving a schema-bounded
+authenticated terminal journal.
+
+Before committing a new plan, the server performs narrowly scoped retention cleanup:
+
+- expired `planned` and `rolled_back` journals are removed by deleting their protected head first
+  and cache journal second. A crash or later reintroduction of the cache copy then fails for a
+  missing head rather than replaying;
+- an incomplete transaction directory with no manifest is removed only after it is older than
+  `transactionTtlSeconds`;
+- `applied`, `failed`, `applying`, and `rolling_back` journals are not quota-evicted. Interrupted
+  states are handled by recovery instead;
+- malformed, integrity-failing, or otherwise unreadable journals are retained and continue to
+  count against quota rather than being guessed safe to delete.
+
+Only the latest protected revision is retained per live journal. Cache-without-head planned or
+rolled-back remnants from an interrupted admission/prune are authenticated and removed safely;
+active or unauthenticated remnants remain fail-closed. Head-without-cache remnants are removed
+while reconciling a workspace. Protected state therefore remains bounded by admitted cache
+journals rather than growing with revision or expiry churn.
+
+After that cleanup, the server deterministically accepts the complete plan or refuses it. It does
+not evict a valid applied/failed journal to make room. Operators who intentionally remove terminal
+journals also remove their status, audit evidence, persisted blobs, and any later explicit rollback
+ability.
+
+Diff artifact creation and journal admission share a failure boundary. If the journal count or byte
+check rejects a plan, the artifact store removes only content and provenance files created for that
+attempt; artifact inventory is unchanged and any identical artifact retained by another operation
+remains addressable.
+
+## Explicit rollback
+
+`hoi4.transaction_rollback` is available after successful apply. It first verifies that every current file still has the transaction's after-hash. An external edit makes rollback stale, protecting later work from being overwritten.
+
+Rollback accepts cancellation through its path/hash verification preflight. Once byte restoration
+starts, restore plus authenticated journal advancement is deliberately non-cancellable so a client
+disconnect cannot strand a partial rollback.
+
+Status/manifest reads and runtime recovery enumeration accept cancellation around filesystem
+reads, JSON/schema validation, and protected-head verification. Once recovery begins restoring
+source bytes, it follows the same non-cancellable critical-phase rule.
+
+Transaction manifests are readable as:
+
+```text
+hoi4-agent://workspace/{workspaceId}/transaction/{transactionId}
+```
+
+Manifest resources use the same 1 MiB `offset`/`length` byte ranges as artifacts. A complete
+strict-UTF-8 manifest may be returned as MCP `text`; every partial range is a base64 `blob`.
+Advance `offset` by the decoded byte count and continue until a chunk is shorter than the requested
+length. Transaction manifests have a separate fixed 16 MiB serialized ceiling, independent of the
+larger rollback-blob journal budget.
+Canonical resource bytes are cached by stable file identity and protected revision, with at most
+eight entries and 16 MiB total, so later ranges do not repeatedly rebuild a large manifest object.

package/docs/troubleshooting.md

@@ -0,0 +1,46 @@
+# Troubleshooting
+
+## Configuration not found
+
+Set `HOI4_AGENT_CONFIG` to an absolute path or add `--config PATH` to the server command. Run `hoi4-agent-tools-setup --diagnose --config PATH`.
+
+## Workspace/path rejected
+
+Use a registered workspace-relative path. Confirm the canonical root is beneath `registrationRoots`; runtime mods also require the separate `writableRegistrationRoots` capability. Check for junctions/symlinks, parent segments, device names, trailing dots/spaces, or alternate data streams. Game and dependencies are intentionally read-only.
+
+## Apply reports stale
+
+The source changed after planning. Do not reuse the transaction. Scan and produce a new dry run so review evidence matches current files.
+
+## Transaction state rejected
+
+Transaction mode requires an absolute, persistent `serverStateRoot` that does not overlap any
+source or generated-storage capability. Run setup with `--enable-writes --server-state ROOT`, then
+run `--diagnose`. Preserve the same private state root across restarts. A missing key, malformed or
+replayed head, unauthenticated legacy manifest, or cache/head revision conflict fails closed; review
+and archive the affected journal/state evidence instead of regenerating a public hash or tag.
+
+## Runtime registration conflicts after restart
+
+The artifact root already has a hash-only runtime owner claim. Register the exact canonical
+workspace as the same principal, or stop the server and perform an explicit operator-reviewed data
+reassignment. Do not delete the claim alone or expect a renamed workspace ID, path alias, or second
+principal to inherit the existing evidence.
+
+## Render has missing/unsupported fields
+
+Read the fidelity resource. Register the correct game/dependency root and supply a scenario value or asset. Unsupported fields stay raw; do not treat an approximation as engine evidence.
+
+## HTTP refuses to start
+
+Authentication is mandatory. Static token secrets must be at least 32 characters and are loopback-only. Public binding requires HTTPS `publicUrl`, OAuth settings, allowed origins, and principal grants.
+
+## HTTP returns 401/403/404
+
+- 401: missing/invalid/expired token or wrong issuer/audience.
+- 403: origin, scope, principal/workspace, or cross-principal session rejected.
+- 404 with session ID: session is unknown or expired; initialize a new MCP session.
+
+## Inspector
+
+Build first, then run `npm run inspector`. The Inspector proxy is a local debugging surface; do not expose it unauthenticated.

package/package.json

@@ -1,18 +1,111 @@
 {
   "name": "hoi4-agent-tools",
-  "version": "0.0.0-bootstrap.1",
-  "description": "One-time non-executable namespace claim for OIDC trusted-publisher setup.",
+  "mcpName": "io.github.klimPaskov/hoi4-agent-tools",
+  "version": "0.1.2",
+  "description": "Source-preserving HOI4 workbench exposed as a safe Model Context Protocol server for coding agents",
+  "type": "module",
   "license": "Apache-2.0",
+  "author": "HOI4 Agent Tools contributors",
+  "homepage": "https://github.com/klimPaskov/hoi4-agent-tools#readme",
+  "bugs": "https://github.com/klimPaskov/hoi4-agent-tools/issues",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/klimPaskov/hoi4-agent-tools.git"
   },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "hearts-of-iron-iv",
+    "hoi4",
+    "modding",
+    "coding-agents"
+  ],
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0"
+  },
   "files": [
-    "README.md"
+    "dist/",
+    "docs/",
+    "schemas/",
+    "server.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "SECURITY.md"
   ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schemas/*": "./schemas/*"
+  },
+  "bin": {
+    "hoi4-agent-tools": "./dist/bin/stdio.js",
+    "hoi4-agent-tools-http": "./dist/bin/http.js",
+    "hoi4-agent-tools-setup": "./dist/bin/setup.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:local": "tsx scripts/run-local-tests.ts",
+    "test:coverage": "vitest run --coverage",
+    "benchmark": "node --expose-gc --import tsx scripts/benchmark.ts",
+    "fixtures:generate": "npm run fixtures:generate:focus && npm run fixtures:generate:gui && npm run fixtures:generate:map",
+    "fixtures:generate:focus": "tsx scripts/generate-fixtures.ts",
+    "fixtures:generate:gui": "tsx scripts/generate-gui-fixture.ts",
+    "fixtures:generate:map": "tsx scripts/generate-map-fixture.ts",
+    "fixtures:check": "npm run fixtures:generate && tsx scripts/check-generated.ts fixtures",
+    "schemas:generate": "tsx scripts/generate-schemas.ts",
+    "schemas:check": "tsx scripts/generate-schemas.ts && tsx scripts/check-generated.ts schemas",
+    "registry:validate": "tsx scripts/validate-registry.ts",
+    "publication:verify": "tsx scripts/verify-publication.ts",
+    "publication:install": "tsx scripts/verify-public-install.ts",
+    "release:artifact:verify": "tsx scripts/verify-release-artifact.ts",
+    "release:order:verify": "tsx scripts/verify-npm-release-order.ts",
+    "pack:check": "tsx scripts/check-package.ts",
+    "inspector": "tsx scripts/run-inspector.ts",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm run test && npm run fixtures:check && npm run schemas:check && npm run build && npm run pack:check && npm run registry:validate",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@fontsource-variable/roboto": "5.2.10",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "express": "5.2.1",
+    "fast-glob": "3.3.3",
+    "fontkit": "2.0.4",
+    "iconv-lite": "0.7.3",
+    "jose": "6.1.3",
+    "sharp": "0.35.3",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@modelcontextprotocol/inspector": "0.22.0",
+    "@types/express": "5.0.6",
+    "@types/fontkit": "2.0.9",
+    "@types/node": "22.20.1",
+    "@types/pixelmatch": "5.2.6",
+    "@vitest/coverage-v8": "4.1.10",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "eslint": "10.6.0",
+    "fast-check": "4.9.0",
+    "pixelmatch": "7.2.0",
+    "prettier": "3.9.5",
+    "tsx": "4.23.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.63.0",
+    "vitest": "4.1.10"
+  },
   "publishConfig": {
     "access": "public",
-    "provenance": false,
-    "tag": "bootstrap"
+    "provenance": true
   }
 }