AI-Game-Dev-CLI-Core

Shared TypeScript CLI core for the AI Game Dev engine CLIs (Unity / Unreal / Godot), published to npm as @baizor/gamedev-cli-core via npm Trusted Publishing (OIDC, tokenless).

This package is the single source of truth for CLI logic; the three engine CLIs are thin, engine-specific adapters over it. The shared modules land here through the auth-fixes design (tasks b2/b3):

• Landed (b2 — correctness/security core):

  • project identity / pin — derivePin/derivePort/deriveProjectPathHash (v1) and the …V2 variants (separator-normalized, the B5 fix), gated byte-for-byte against the SAME golden vectors as the C# LIB (test/golden-vectors/, vendored from MCP-Plugin-dotnet).
  • machine credential store — MachineCredentialStore at ~/.ai-game-dev/credentials.json, full MachineCredentials, DPAPI on Windows / 0600 on POSIX, atomic (crash-safe) writes.
  • OAuth 2.1 device-grant login — deviceLogin (RFC 8628, /oauth/device_authorization + /oauth/token) with token rotation and a clean login required on family-revoke.

• Landed (b3 — shared modules + the engine-adapter contract):

  • engine-adapter contract — EngineAdapter (+ unityAdapter / unrealAdapter / godotAdapter), the single typed seam that carries every per-engine difference: serverName, project markers, stdioSupported + stdioArgs, the server install-dir layout, loginServerTarget, and the OAuth clientId. No engine specifics live anywhere else in the package.
  • agent-config writers — JsonAiAgentConfig / TomlAiAgentConfig, byte-for-byte parity with the C# com.IvanMurzak.McpPlugin.AgentConfig, gated by test/golden-vectors/AgentConfig.GoldenVectors.json, plus the engine-neutral agentRegistry.
  • setup-mcp policy — setupMcp / resolveSetupMcpPlan: pins the routing URL by default (/mcp/p/<pin-v2> http, project=<pin> stdio; B4), with a --no-pin escape hatch, and writes a static credential only on an explicit --token opt-in (M7 — the default config is credential-free; the pin is routing-only, not part of the OAuth resource — M8).
  • install-plugin policy — resolveInstallTarget: resolves the project path positional → --path → cwd (B1) then marker-probes it, failing with a message listing exactly what was checked. Ancestor walk-up is out of scope (M5).
  • enroll — runEnroll / redeemEnrollmentCode: writes the v2 pin (the B5 fix replaces the Unity CLI's local \→/ workaround) and records the AS-root serverTarget, never a pinned hub URL (b2 review MED-2).
  • server-download — downloadServer with a fail-closed SHA256SUMS verify-before-execute gate and a dependency-free in-process parseZip unzip.
  • project-marker, validation, ui/progress utilities.

• Landed (c1/c2 + DCR — desktop browser sign-in):

  • OAuth 2.1 authorization-code login — authCodeLogin (RFC 8252 native app, RFC 7636 PKCE S256, state CSRF check, an ephemeral 127.0.0.1 loopback listener, RFC 8707 resource), returning the same MachineCredentials shape as deviceLogin.
  • Discovery + dynamic client registration — discoverAuthorizationServer (RFC 8414 /.well-known/oauth-authorization-server, falling back to the hardcoded paths) and resolveClientRegistration / registerClient (RFC 7591). /oauth/authorize resolves client_id by an exact registry lookup whose only writer is POST /oauth/register — which mints its OWN id — so a hardcoded client id is always rejected with invalid_client. The minted id is persisted per authorization server in ~/.ai-game-dev/oauth-clients.json (ClientRegistrationStore, same atomic owner-only write as the credential store) and reused on every later launch; only the loopback port floats, so one registration serves every run. On invalid_client the flow re-registers exactly once. The device grant deliberately keeps its static client id — the server binds each refresh-token family to the id used at issue time, so moving it would invalidate every existing CLI login.

• Landed (unified-machine-auth c3 — the shared refresher/provider + login plumbing):

  • MachineCredentialProvider — THE single entry point for credential access + refresh. The three engine CLIs (W2: d2/e2/f2) and the desktop App (W3) obtain access tokens EXCLUSIVELY via getAccessToken({family}) / refresh({family}); nothing else re-implements refresh. It is family-aware over store schema v2 (agent / plugin / legacy planes), runs every refresh under the cross-process MachineCredentialLock with a double-checked re-read (a peer's rotation is adopted without a network call), presents the family's stored clientId (component default ONLY for families.legacy), omits scope/resource on refresh (P0-3), keeps the previous refresh token when the server does not rotate one, treats invalid_grant after a post-failure re-read as family death (one structured telemetry event, other families untouched, never loops), rate-limits to one attempt per family per skew window, and surfaces busy locks / unreadable stores as typed non-sign-out errors.
  • RFC 8693 token exchange — HttpTokenExchangeClient (the frozen a5 wire shape: subject_token = fresh agent access token, exact URNs, scope=mcp:plugin, audience only as the exact urn:agd:hub), deriving the plugin family from the agent family.
  • Login-surface commit plumbing — commitAgentLogin (the F1/F2 two-lock-hold sequence: agent family under hold 1 → exchange → plugin family + v1 mirror under hold 2; a failed exchange leaves the committed agent family and a "partially authorized, retrying" state resumable via derivePluginFamily), commitToolsOnlyLogin (the --tools-only / O10 plugin-only mint for CI — F10), the D6/F7 account-switch guard (evaluateAccountSwitch / runAccountSwitchGuard; decline revokes the just-minted family and leaves the store untouched; runEnroll routes through the same guard), signOutMachineWide (F6: best-effort RFC 7009 revocation of every family, then the lock-guarded store delete), and revokeTokenBestEffort (RFC 7009). Every commit re-verifies the world under its lock hold before writing (commitFamilyUnderHold): a guard premise that changed during the confirm dialog, a subject switched between the two holds, a store deleted by a concurrent sign-out (never recreated), or a store turned unreadable (never overwritten) each abort with a typed CommitAbortReason result — never a throw, never a mixed-account or resurrected store.

A small semver utility slice is also exposed. The package has zero runtime dependencies.

Requirements

• Node.js >= 22.14.0
• npm >= 11.5.1 (required for OIDC Trusted Publishing; below this the publish silently degrades)

Develop

npm install       # install dependencies
npm run build     # tsc -> dist/ (ESM + .d.ts)
npm test          # vitest run
npm run typecheck # tsc --noEmit

Release (npm Trusted Publishing / OIDC)

Releases are cut from the release.yml GitHub Actions workflow, which publishes to npm over OIDC (no npm token, no --provenance flag — provenance is attached automatically). Run it from your machine with the GitHub CLI:

gh workflow run release.yml -f version=X.Y.Z

The workflow enforces the Node >= 22.14.0 / npm >= 11.5.1 floors, sets the package version from the version input, builds, and publishes.

Trusted Publishing binding (owner, one-time)

The npm Trusted Publisher for @baizor/gamedev-cli-core is bound to this exact repo + workflow (.github/workflows/release.yml). The publish step lives directly in that workflow file — it is not factored into a reusable workflow, because reusable-workflow bindings are a known npm TP limitation for workflow_dispatch.

License

MIT © Ivan Murzak