feat: package ecosystem — configurable dependency orchestration via charter config

[stackbilt-admin]

Motivation

Charter already manages governance, ADF context, and scaffolding. The next natural extension is dependency orchestration — letting projects declare which packages from the broader ecosystem they use, and having Charter wire them in during scaffold, validate them in doctor, and expose them through ADF.

Today, adding a multi-LLM provider layer or contract ontology to a Worker project means manually installing packages, configuring wrangler.toml bindings, writing import boilerplate, and keeping versions compatible. Charter can automate this.

Proposal: packages config section

Extend .charter/config.json (or charter.config.ts for type-safe configs):

{
  "stack": "worker",
  "packages": {
    "@stackbilt/llm-providers": {
      "enabled": true,
      "config": {
        "primary": "cloudflare",
        "fallback": ["groq"],
        "circuitBreaker": true
      }
    },
    "@stackbilt/contracts": {
      "enabled": true,
      "config": {
        "generators": ["sql", "routes", "sdk"]
      }
    }
  }
}

Package registry

Each ecosystem package registers a descriptor:

export interface CharterPackageDescriptor {
  name: string;
  description: string;
  npmPackage: string;
  configSchema: z.ZodType;        // Zod schema for package-specific config
  scaffoldTemplates?: string[];    // Files to generate during scaffold
  adfModule?: string;              // ADF context to inject during populate
  doctorChecks?: DoctorCheck[];    // Health checks for doctor command
  wranglerBindings?: string[];     // Required wrangler.toml entries
}

CLI integration points

Command	Package behavior
charter init	Prompt for packages to enable, write config
charter scaffold	Include package-specific setup (imports, bindings, boilerplate)
charter doctor	Validate packages installed, versions compatible, bindings configured
charter adf populate	Inject package-specific ADF context modules
charter serve	Expose package tools through MCP server

Compatible packages

Any package that ships a CharterPackageDescriptor can participate. Current candidates from the ecosystem:

• @stackbilt/llm-providers — multi-LLM failover + circuit breakers
• @stackbilt/contracts — ODD contract ontology + code generators
• @stackbilt/audit-chain — tamper-evident hash-chained audit trail
• worker-observability — structured logging + tracing for edge workers

Design constraints

• Config schema must be Zod-validated (consistent with existing Charter patterns)
• Packages are optional — Charter works fine with zero packages enabled
• No lock-in: packages are standard npm deps, Charter just orchestrates the setup
• Package descriptors live in the package repos, not in Charter (decentralized)
• charter doctor must clearly report which packages are configured vs. installed vs. misconfigured

Prior art

• Astro integrations (astro.config.mjs → integrations: [...])
• Nuxt modules (nuxt.config.ts → modules: [...])
• Angular schematics
• Nx generators

The difference: Charter's package system is governance-aware. Packages can declare ADF context, policy requirements, and audit hooks — not just code scaffolding.

Sequencing

1. Define CharterPackageDescriptor interface + config schema in @stackbilt/core
2. Wire first package (@stackbilt/llm-providers) as proof of concept
3. Extend charter doctor for package validation
4. Extend charter scaffold for package-specific file generation
5. Extend charter adf populate for package context injection

[stackbilt-admin]

Status update — @stackbilt/cli@0.10.0

Partial building blocks for this proposal shipped in 0.10.0:

• @stackbilt/blast — reverse dependency graph + blast radius analysis. Could back a charter check-compat style command that evaluates whether adding/removing a package affects the current import graph.
• @stackbilt/surface — route + D1 schema extraction. Gives governance tooling visibility into what a package's dependents actually expose, which is a prerequisite for safe dependency orchestration.

Neither of these implements the package ecosystem feature described here — they're foundational analysis primitives. But when we do build package orchestration, they'll slot in as:

• Pre-install: charter can blast-radius the target files to understand which parts of the project a new dep will touch
• Post-install: charter can diff the surface before/after to verify the dep didn't silently change the API

Keeping this issue open as a design-stage feature request. No scheduled work on it yet.