Formalize the apps/plugins/packages dependency-direction rule

Abierto
  • ¿Algo no está bien?
#122 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
45/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
typescript
Área
cli, documentation, tooling

Línea de trabajo

Lee AGENTS.md, CONTRIBUTING.md y DEVELOPMENT.md para decidir dónde debe ubicarse la regla de dirección de dependencias, y luego revisa src/cli.ts y la estructura del workspace junto con issue #121. Documenta la regla y la decisión de clasificación, registra la auditoría actual y las acciones de seguimiento, y determina si se puede especificar una comprobación ligera de límites en CI sin ampliar el alcance.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
TypeScript
Estrellas
20
Forks
11
Merge medio
5 h 28 min
PR fusionados (30 d)
4

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de game-ci/cli

Todos los issues de game-ci/cli

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.