Development

Development

The CLI repository owns command parsing, adapters, JSON/MCP schemas, tests and plugin files. The upstream Toolkit owns the parser, game profiles, localization policy, Tiger helpers, migration engine and texture codecs. Keep game knowledge in upstream profiles and source evidence.

Build and check

Use Node 22.22.2 or newer and pnpm. Work on a feature branch and keep fixtures under ignored .local/.

pnpm install --frozen-lockfile
pnpm run compile
pnpm run typecheck
pnpm run lint
pnpm test
pnpm pack --pack-destination .local/artifacts
pnpm test:package .local/artifacts/pxtk-cli-0.2.1.tgz

Compilation produces the CLI, its stdio LSP and required bundled data. The package test installs the archive into an isolated directory and exercises the installed command without a Toolkit checkout. It includes research, writers, image inspection and failure behavior. Optional native image dependencies must resolve for the consumer platform. A source test pass alone does not prove a packaged install works.

Real validation

Copy dev-paths.example.json to ignored dev-paths.json and configure actual CK3 game-data and Tiger paths, or use PX_CK3_GAME_PATH, PX_CK3_LOGS_PATH and PX_CK3_TIGER_PATH:

pnpm test:real

Generated mods and reports stay under .local/; game files remain read-only. Report missing corpus settings and actual game/validator versions. Version mismatch and incomplete validation remain failures or explicit limitations, not a gameplay certificate.

Verification on 5 October 2026

Workflow commit 63f0365 passes all four CI jobs: Windows and Ubuntu with Node 22.22.2 and 24. Each job runs frozen installation, compilation, typecheck, lint, all 194 tests, packaging and an installed-tarball exercise. The tests cover actual CLI commands, a real MCP client, all seven added workflows, stale previews, read-only boundaries, interrupted writes and worker termination. The standalone package includes all 21 tools and its migration worker. The two shared-core fixes also pass 126 focused upstream tests.

The local CK3 exercise verifies rename, precise edits, translation sync, ordered conflicts and release staging on scratch mods, plus byte-identical import of an installed vanilla resource. It checks source preservation, existing-destination refusals, migration catalog and exact-build routes. CK3 1.20.0.3 is newer than installed Tiger 1.19.0 supports, so deep validation correctly remains incomplete and baseline creation is refused. No exact old-build game corpus was supplied; complete preparation of a compatible built-in CK3 migration remains unverified. Migration preparation is covered by synthetic recipe fixtures. No migration was applied and gameplay was not tested.

A loaded local Windows run hit timing limits in existing launcher fixtures. All 13 launcher tests passed when run alone, with their assertions and production observation window unchanged; the full suite passed on every clean CI runner.

Shared core snapshots

The core packages required by the CLI are pinned in vendor/toolkit-core/. manifest.json records the upstream revision, package versions and archive checksums. A checkout can build without a second repository or machine-specific package links. Published registry dependencies can replace archives when they contain the required APIs.

Maintain core fixes in Toolkit source, not by editing archives or installed packages. Import from a Toolkit checkout with committed changes and installed build dependencies:

pnpm core:import <toolkit-checkout>
pnpm install

Review the manifest, archive and lockfile changes, then run the checks above. The recorded upstream commit can remain local until the Toolkit publishes it; the bundled archive source remains available in the CLI repository.

Contracts and tests

src/contract.ts extends the base types from @px-lsp/protocol/agentTools. src/requests.ts defines strict operation inputs; src/responses.ts defines MCP outputs. Keep those contracts, CLI parsing, MCP tool discovery and docs/PROTOCOL.md aligned. JSON mode and MCP must keep stdout machine-readable.

Writers preview by default, require explicit authorization, refuse stale inputs and protect unrelated content. Game and dependency files are read-only. Verify behavior through actual CLI or MCP entry points, including refusal paths and packaged installation. Headless checks are static evidence; use an actual game observation for runtime claims.

Publishing

Packing builds a local archive and does not publish it. Commits, pushes, remote creation, registry publication, release publication and wiki publication are separate explicit actions. Version 0.2.1 is distributed as pxtk-cli on npm, @jdeffner/pxtk-cli on GitHub Packages and a GitHub release archive. Both registry packages provide pxtk. The release README, protocol and changelog provide the versioned repository record.

For a release:

1. Set the same version in package.json and both plugin manifests, and update the changelog and current installation examples.
2. Run all build and package checks. Writer or validation changes also require the real validation exercise and a report of any missing corpus or version mismatch.
3. After checks pass, commit the release changes and push a matching v<version> tag. publish-npm.yml publishes pxtk-cli; publish-github.yml publishes @jdeffner/pxtk-cli and verifies its installed command.
4. Create the GitHub release with the tested pxtk-cli-<version>.tgz archive and SHA256SUMS.txt.

npm Actions publication uses trusted publishing with OIDC and needs no stored npm token. Configure the package's trusted publisher once with owner JDeffner, repository paradox-toolkit-cli and workflow filename publish-npm.yml. Enable direct publication with pnpm dlx npm@11.21.0 trust github pxtk-cli --file publish-npm.yml --repo JDeffner/paradox-toolkit-cli --allow-publish --yes; a new trust permits staging only by default. Builds and checks use pnpm; npm publication uses the npm CLI. A manual run of publish-npm.yml verifies OIDC only. A manual run of publish-github.yml verifies registry installation only. Neither manual run publishes a version.