create-stellaris-mod
v0.8.0
Published
Scaffold a Stellaris mod project that builds with @pdx-ts/sdk
Maintainers
Readme
create-stellaris-mod
create-stellaris-mod scaffolds Stellaris mod projects for
@pdx-ts/sdk. It can also inspect a built-in Recipe Catalog
and add curated Feature source to an existing project.
The CLI produces source code the author owns. It is not a runtime dependency of the generated mod.
Requirements and quick start
The CLI requires Node.js 22 or newer. Generated projects require Node.js 22.18 or newer because their scripts execute erasable TypeScript directly.
npx create-stellaris-mod my-mod
cd my-mod
npm run inspect
npm test
npm run build
npm run install-modcreate-stellaris-mod my-mod is an alias for the canonical command:
npx create-stellaris-mod init my-modThe CLI finds the local Stellaris installation when possible and reads the game
version from launcher-settings.json. A supported three-part version selects
the matching identifier package; missing or unsupported version data falls back
to the build this scaffolder was verified against. The generated project
typechecks, tests, and builds after installation.
First five minutes
- Edit the mod name, version, tags, or supported game version in
stellaris-mod.json. - Open
src/features/example.tsto see a technology, event, and on-action hook in one Feature, andsrc/features.tsto see the line that puts it in the mod. - Run
npm run inspectto review Feature stems, Item ids, dependency versions, vanilla evidence, patch plans, and warnings as deterministic YAML. - Run
npm testto execute the example event chain without launching the game. - Run
npm run buildto writeout/, ornpm run install-modto place the built mod where the launcher expects it.
The generated README repeats these project-specific commands and records the
game-version pin chosen during scaffolding. The commands above assume the npm
default; the generated README, AGENTS.md, and the terminal next steps all
spell them with the package manager --pm selected, so a pnpm or Bun project is
never told to run npm install.
Commands
init
Create a new project:
npx create-stellaris-mod init my-modThe destination must not already exist, even as an empty directory. The planner resolves every prompt before publication, and cancellation leaves the target unchanged.
list
List the recipes included in this release:
npx create-stellaris-mod listview
Describe a recipe, its generated topology, its questions, and the flags that answer those questions without prompting:
npx create-stellaris-mod view technologygenerate
Write one Feature source file into an existing project and declare it in the Feature list:
npx create-stellaris-mod generate technology "Resonance Theory"generate searches upward for stellaris-mod.json, checks for a string
package.json#imports.#mod mapping and a supported SDK range, writes
src/features/resonance_theory.ts, and appends one line to src/features.ts:
export { feature as resonanceTheory } from "./features/resonance_theory.ts";It never overwrites an existing file, directory, or symlink, and it never
creates or rewrites src/features.ts: the list must already exist as a regular
file, and a list that already declares the module's path or already exports the
binding is refused with the line number. The module is written first; if the
append then fails, the module is removed again, so the project never holds a
feature module its list does not name. --dry-run prints the exact source and
the line it would append without creating directories or files. A successful
normal run writes only the created path to stdout; the appended line is reported
on stderr.
Publication holds the destination directory and temporary file open while it
checks their identity before and after creating the final hard link. Node does
not expose descriptor-relative openat or linkat, so pathname publication
cannot guarantee containment against a hostile process that concurrently
replaces project directories. Do not generate while an untrusted process can
rename project directories.
Generated project
my-mod/
|-- stellaris-mod.json Project Manifest and mod identity
|-- stellaris-mod.schema.json local editor schema
|-- package.json
|-- tsconfig.json
|-- vitest.config.ts
|-- knip.json the dead-file check behind `npm run lint`
|-- eslint.config.js omitted with --no-eslint
|-- .prettierrc omitted with --no-prettier
|-- assets/ create when the first Asset is needed
`-- src/
|-- mod.ts createModProject: project, config, and mod
|-- build.ts buildTheMod, the one Fold every command shares
|-- features.ts the Feature list: one line per Feature
|-- index.ts render and write out/
|-- inspect.ts Fold and print deterministic YAML
|-- install.ts build and install for the launcher
|-- vanilla.ts parsed install, when one was found
|-- flags.ts shared typed values
`-- features/
|-- example.ts named Feature export
`-- example.test.ts colocated mod-logic testAgent support files are also generated by default and are described separately below.
Project Manifest and build pipeline
stellaris-mod.json is the single author-owned source of truth for mod identity,
launcher metadata, and the Asset tree. Its mod object contains exactly one
key, the mod prefix:
{
"$schema": "./stellaris-mod.schema.json",
"mod": {
"my_mod": {
"name": "My Mod",
"version": "0.1.0",
"supportedVersion": "4.4.*",
"tags": []
}
},
"assetsDirectory": "assets"
}The object key preserves the prefix as a TypeScript literal. assetsDirectory
mirrors opaque files into the built mod root. Feature source is not in the
manifest: src/features.ts, the Feature list, declares it.
The generated package maps #mod to ./src/mod.ts. Feature modules import the
capability through that stable alias instead of computing relative paths.
Importing mod.ts does not compile or touch disk, and it imports nothing else
of the project: feature modules import it, so a static import of the Feature
list from mod.ts would evaluate them before mod exists. src/build.ts is
the module that imports both sides, and its buildTheMod() owns the
conventional sequence:
validate manifest
-> create immutable capability
-> import the Feature list as a namespace
-> load vanilla view when configured
-> capture Assets
-> Fold once, over exactly the declared FeaturesThe build, inspect, and install commands call that same sequence and then add their one final operation. A custom project can compose the SDK's lower-level interfaces directly.
The Feature list is the only thing that puts a module in the mod, so a module
under src/features/ that no line names is dead code that still compiles and
passes its tests. npm run lint runs knip with only two
reports on, unused files and unresolved imports, and reports such a module by
path. Every other knip report is off in knip.json: unused exports are the
norm in a feature module, and the vitest plugin is disabled so a module
reachable only through its own test does not pass the check.
src/vanilla.ts returns no view in exactly two cases: PDX_NO_VANILLA=1, and
the SDK finding no install on its own. Every other failure — an unreadable game
directory, a game whose shape the parser does not recognize, a corrupt archive —
propagates and the build reports it. An unexpected failure is not evidence that
there is no game, and a build that silently drops id-collision checks, version
evidence, and patch sources cannot be told apart from one that kept them.
A STELLARIS_PATH that is not a game root propagates too, matching the CLI's
own rule that an explicit invalid path is fatal. A path baked in by scaffolding
is treated the opposite way: it records one machine rather than requesting
anything here, so a checkout where it does not resolve still builds without the
view.
Recipe Catalog
Recipes generate short, working TypeScript starters. An Item recipe emits one Feature containing one Item. A Feature recipe coordinates several Items when a useful example needs event chains, references, or shared script.
Recipe questions cover structural intent: topology, scope contracts, control flow, authoring kind, and cross-Item relationships. Values that are easier to edit in source are left in source instead of becoming prompts.
Each recipe owns a pure renderer from validated answers to one source file. The Catalog does not derive templates by walking SDK field metadata, and it does not create a second authoring schema.
With --yes, or when stdin is not a terminal, generate requires the recipe id
and name and uses every recipe default. view <recipe> lists all available
question flags.
Install discovery and version pinning
The CLI uses --stellaris-path first, then STELLARIS_PATH, then the platform's
normal Steam locations. A missing automatically detected install is not fatal:
the project still writes src/vanilla.ts, which finds the install later if one
appears, and pins identifiers to the Stellaris build this scaffolder was
verified against.
An explicit invalid --stellaris-path is fatal. Treating a misspelled path as a
request to disable install checks would hide user intent.
The generated dependency range has the form:
"@pdx-ts/stellaris-ids": ">=4.4.6-0 <4.4.6"It selects the newest package revision for one exact game build. Immediately after a Stellaris update, the matching npm release may not exist. The CLI reports that case and asks the author to wait for the release or choose a game build that has one.
Safety and automation
Every configurable init prompt has a flag. The target directory remains a
positional argument. For generate, recipe questions have flags while the
recipe id and generated name remain positional. --yes, or non-terminal stdin,
accepts defaults without waiting for input and requires those positionals.
--name <string>
--prefix <snake_case>
--stellaris-path <path>
--supported-version <v4.4.*>
--tags <a,b>
--local <path>
--pm <command> # npm, pnpm, yarn, and bun are the detected common cases
--dry-run
-y, --yes
--no-prettier
--no-eslint
--no-llm
--no-git
--no-installGeneration-specific flags are:
--cwd <path>
--yes
--dry-run
--allow-unsupported-sdk--allow-unsupported-sdk changes one compatibility refusal into a warning. It
does not load the SDK, weaken the generated code, or promise that a later build
will pass.
On platforms where symlink creation returns EPERM, publication falls back to
regular file and directory copies. This keeps the default project usable on
Windows without symbolic-link privileges.
Optional agent support
The default project includes shared AGENTS.md guidance, project-scoped skills,
and Codex and Claude definitions for an SDK documentation expert. All files stay
inside the generated project; initialization does not edit user-level agent
configuration or download external skills.
The generated agent instructions tell the documentation expert to compare the project's SDK dependency with documentation provenance before giving API advice. This is an agent workflow instruction, not a separate compatibility checker in the CLI.
AGENTS.md carries the second half of that comparison in its
Documentation provenance section: the @pdx-ts/sdk range the project was
scaffolded against, and the SDK source revision behind it. The documentation
site publishes the same hash as the SDK revision: line in its llms.txt, so
the two agree exactly when the fetched documentation was generated from the SDK
source this project was scaffolded against. It records one moment rather than
checking continuously: once the project declares a version outside that range,
the recorded revision describes an older SDK and the version match governs
alone.
A project scaffolded with --local records no provenance and says so. Its
@pdx-ts/sdk is a file: link at a checkout, which is neither a published
version nor a fixed revision, so there is nothing for published documentation to
match. Recording the release coordinates anyway would point the documentation
expert at a version the project does not depend on.
Use --no-llm to omit the complete bundle.
Local SDK development
Point --local at an unreleased repository checkout to scaffold a consumer
against local packages:
npm run build # in the pdx-sdk checkout first
npx create-stellaris-mod my-mod --local ~/code/pdx-sdkThe project receives file: dependencies. Build the checkout first because an
external project resolves published dist/ exports. The monorepo's internal
pdx-source condition is deliberately not part of the consumer contract.
Implementation
The published CLI is compiled TypeScript and ESM. It uses @clack/prompts for
interactive terminals and semver for dependency compatibility. Generated
projects use strict TypeScript, Vitest, optional ESLint and Prettier, JSON Schema
validation, and the selected package-manager command.
The public module exports main, processIo, CliIo, and
detectPackageManager. main(argv, io, terminal) returns an exit code and uses
injected I/O, which lets tests run the complete command router without calling
process.exit.
Internally, resolution and publication are separate:
CLI arguments and prompts
-> resolved configuration
-> pure scaffold or recipe plan
-> exclusive filesystem publication
-> optional package installation and git initializationsrc/plan.ts returns a map of regular files and relative symlinks without
touching disk. Recipe renderers are also pure. The filesystem layer publishes
only after validation succeeds.
Development and verification
Run from the repository root:
npm run scaffold -- --help
npm run scaffold -- --dry-run --yes /tmp/demo
npm run typecheck
npm test
npm run buildThe end-to-end scaffold test creates a temporary project and runs its real
typecheck, lint, build, and tests. This is the main guard against invalid
TypeScript inside string templates, and it proves knip resolves #mod and the
.ts imports the way Node and TypeScript do. Unit tests cover pure plans, option parsing, command
routing, Recipe variants, safety refusals, and cross-platform publication.
See the Scaffolding glossary for Recipe and Project Manifest terminology.
