Formalize the apps/plugins/packages dependency-direction rule

Aperta
  • Qualcosa non va?
#122 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
45/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
typescript
Ambito
cli, documentation, tooling

Direzione di ricerca

Leggi AGENTS.md, CONTRIBUTING.md e DEVELOPMENT.md per scegliere dove collocare la regola sulla direzione delle dipendenze, poi esamina src/cli.ts e la struttura del workspace insieme a issue #121. Documenta la regola e la decisione di classificazione, registra l’audit corrente e le attività successive e determina se sia possibile specificare una verifica leggera dei confini in CI senza ampliare l’ambito.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

The rule

From internal discussion, the intended layering for this monorepo:

/apps can rely on /packages
/plugins can rely on /packages
/packages can rely on other /packages (but only 1 way, never circular)

/apps can not rely on /plugins (plugins are self contained, and are loaded using
  a mechanism, not direct dependency)
/plugins can not rely on /apps, if it needs to then that part has to be moved
  into a /packages module

Nothing in the repo currently documents this explicitly (not in AGENTS.md, CONTRIBUTING.md, or DEVELOPMENT.md). This issue is to (a) record the rule somewhere real, and (b) track where the actual repo layout does/doesn't hold up against it, since it was never checked mechanically before.

Current state (audited 2026-08-24)

The repo is two-tier today: src/ (the game-ci CLI — the app) + plugins/* (two workspace packages: @game-ci/orchestrator, @game-ci/unity-engine-core). There is no /packages tier at all.

Checked against each rule literally:

  • /apps can rely on /packages — N/A, no packages exist.
  • /plugins can rely on /packages — N/A, same.
  • /packages can rely on other /packages (one-way) — N/A, no packages tier.
  • /apps can not rely on /plugins — was violated: src/cli.ts statically imported orchestratorPlugin directly from plugins/orchestrator/src/cli-plugin/index.ts (a relative path into a plugin's private internals) to make orchestrate work without requiring --plugin @game-ci/orchestrator-plugin. Fixed in #121 — orchestrator is now loaded through PluginLoader.load('@game-ci/orchestrator/cli-plugin') (its public package export), same mechanism as any other plugin; it's just always in the default load list. Two things had to be fixed to make that actually work, not just compile — see #121's description for the full writeup: (1) the root package.json never declared a dependency on @game-ci/orchestrator at all, so there was no workspace symlink to resolve the package name through; (2) @game-ci/orchestrator's exports map only pointed at compiled dist/, which would have introduced a new, currently-unwired build-order dependency (orchestrator's own tsc build would need to run before the root CLI's bun build) — solved with a "bun" export condition pointing at TypeScript source directly, so bundling stays byte-identical to before (1756 modules, 10.52MB, verified with zero pre-built orchestrator dist/ present).
  • /plugins can not rely on /apps — held. Neither orchestrator nor unity-engine-core imports anything from src/.

Open question: is "plugin" even the right classification for these two?

@game-ci/orchestrator and @game-ci/unity-engine-core don't depend on src/ or on each other, so they technically satisfy the plugin rules as written. But they don't share a /packages tier for common needs either — each independently vendors its own copies of overlapping dependencies (@actions/core, @actions/exec, nanoid, semver, yaml, etc.) rather than depending on one shared module. That's not a rule violation (there's no cross-plugin reliance happening to route through /packages), but it's exactly the situation the /packages tier exists to solve once it's needed.

Separately: @game-ci/orchestrator ships its own standalone bin entry ("game-ci": "./dist/cli.js") and can also be loaded as a fully out-of-process executable plugin via the executable:/CLI-protocol path (CliProtocolPlugin) — i.e. it has real independent-app characteristics, not just "extends the host app" characteristics. @game-ci/unity-engine-core has no bin entry and no standalone identity — it's closer to a pure library. Worth deciding explicitly whether "plugin" here means "a thing dynamically loaded into game-ci to extend it" (a consumption mode, which a package can have alongside also being runnable standalone) or a stricter category that excludes anything with independent app identity. Current lean: the two aren't mutually exclusive — a single workspace package can be both "an app" (has its own entrypoint, runs standalone) and "a plugin" (also exposes a GameCIPlugin-shaped export the host can dynamically load) — but this should be a deliberate call, not an accident of how things were built.

Follow-ups this issue should track

  • Document the apps/plugins/packages rule somewhere real (AGENTS.md or a new ARCHITECTURE.md)
  • Decide the open classification question above and record the decision
  • If/when orchestrator and unity-engine-core end up needing to share code, factor it into a real /packages tier rather than duplicating it further
  • Consider a lightweight CI check (e.g. an import-boundary lint rule) that would have caught the src/cli.ts violation automatically, so this class of drift doesn't require a manual audit to notice again
Lingua principale
TypeScript
Stelle
20
Fork
11
Merge medio
5h 28m
PR unite (30g)
4

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di game-ci/cli

Tutte le issue di game-ci/cli

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.