MafiaHub Services CLI

Build publishing and scripting API documentation tooling for MafiaHub mods.

Generate scripting API documentation

The CLI converts schema-v2 binding metadata emitted by the MafiaHub v8pp integration into TypeScript declarations, checks those declarations against C++ binding names, validates them with TypeScript, and renders static HTML and TypeDoc JSON.

npm install --save-dev @mafiahub/services-cli
npx mafiahub-services docs check --config ./scripting-api/docs.config.json
npx mafiahub-services docs generate --config ./scripting-api/docs.config.json --out ./build/docs

Mods own docs.config.json, declarations, guides, and theme overrides. The configuration schema is published at node_modules/@mafiahub/services-cli/schema/scripting-docs.schema.json. Metadata-backed targets must define both metadataFile and generatedEntryPoint; the mod build is responsible for producing the metadata JSON before invoking the CLI.

Native event contracts can be exported as a metadata data type named EventMap. Define one property per event and use a named TypeScript tuple for its callback arguments, such as [player: Player, text: string]. The generated declarations preserve that interface as the event reference and add type EventName = keyof EventMap, keeping event-name autocomplete and the HTML event list derived from the same runtime metadata.

Custom Markdown documents can be included for every API target with top-level documents, or for one target with targets.<name>.documents. Paths and glob patterns are resolved relative to docs.config.json. TypeDoc adds these pages to navigation and copies locally referenced images into the generated static bundle.

{
    "schemaVersion": 1,
    "slug": "example-mod",
    "title": "Example scripting API",
    "tagline": "Reference and guides for Example Mod.",
    "readme": "documentation/README.md",
    "documents": ["documentation/guides/**/*.md"],
    "targets": {
        "client": {
            "label": "Client API",
            "entryPoint": "generated/client.d.ts",
            "tsconfig": "tsconfig.json",
            "description": "Client scripting APIs.",
            "documents": ["documentation/client/**/*.md"]
        }
    }
}

Keep images beside their guides and reference them with relative Markdown paths, for example ![Server browser](./assets/server-browser.webp).

Publish artifacts

mafiahub-services builds publish \
    --api-url https://api.example.com \
    --mod-id 00000000-0000-0000-0000-000000000000 \
    --channel stable \
    --version 1.0.0 \
    --root ./dist/game

Set MAFIAHUB_BUILD_UPLOAD_TOKEN in CI, or pass --token / --token-file.

--api-url accepts either the API base URL or its /graphql endpoint. Build publishing uses the initBuildUpload and finalizeBuildUpload GraphQL mutations; the build token is sent as X-MafiaHub-Build-Token only to that endpoint and is never forwarded to presigned upload URLs.

The CLI build regenerates apps/api/schema.graphql from the NestJS code-first resolvers, then uses GraphQL Code Generator to produce typed documents in src/generated/graphql.ts. Schema drift therefore fails during code generation or TypeScript compilation instead of at runtime.

Publish a generated static scripting documentation bundle:

mafiahub-services docs publish \
    --api-url https://api.example.com \
    --mod-id 00000000-0000-0000-0000-000000000000 \
    --channel stable \
    --version 1.0.0 \
    --root ./build/docs/m2o

Set MAFIAHUB_DOCS_UPLOAD_TOKEN in CI. Documentation credentials are scoped separately from binary build uploads.