Skip to main content

Architecture and data flow

Package Ninja separates governance control from local command execution.

Control plane components​

  • dashboard web app (workspace operations UI)
  • backend functions (auth bridge, policy APIs, billing/event handling)
  • firestore data model (orgs, teams, policies, memberships, events, sessions)

Data plane components​

  • CLI/runtime (package-ninja canonical command name)
  • local runtime process and session manager
  • shared workflow planner used by package-ninja plan and governed execution commands
  • first-class package-manager passthrough for npm-family tooling (npm, pnpm, yarn, bun)
  • production runtime adapters for PyPI, Cargo, Go modules, NuGet, Maven/Gradle, and Composer

Command data flow​

  1. developer runs command in local terminal
  2. CLI resolves project root, detected ecosystem, and native command plan
  3. CLI resolves local auth session and active workspace identity
  4. CLI requests effective policy when execution requires enforcement
  5. CLI evaluates preflight and produces verdict
  6. audit event is emitted
  7. command executes or blocks based on verdict

package-ninja plan --json stops after step 2 and reports the planned command, risk class, freshness requirement, artifact inspection, and audit behavior for humans, CI, and agents.

Security design principles​

  • do not trust client-provided org/team identifiers
  • derive effective org/team from verified auth context server-side
  • enforce deny-first semantics for ambiguous policy conflicts
  • rotate and revoke tokens aggressively for stolen-device resilience

How should you think about ecosystem support?​

Package Ninja is not a single-registry npm filter anymore, but it also does not expose every adapter as an equal first-class workflow yet.

  • The runtime proxy and policy layer are already multi-ecosystem.
  • The main CLI workflow commands now auto-detect the current production adapter set for universal restore, supported add/remove, and test, while higher-level convenience verbs such as publish and some dev flows still remain ecosystem-specific. Governed fix now supports direct safe-version remediation for the ecosystems that already have safe upgrade semantics.
  • The hosted package intelligence surface already reaches into several registries beyond npm.

Use the full breakdown here: