feat: Framework-agnostic build pipeline for CNB/Buildpack support

[Huijiro]

Summary

Reworks agentuity build and agentuity deploy from a single-framework bundler (Agentuity native only) into a framework-agnostic build and deploy system. Any JS/TS project can now be built and deployed through Agentuity.

How it works

Both agentuity build and agentuity deploy now follow a detect → build → package pipeline:

agentuity build / deploy
    │
    ├─ 1. Detect framework (what is this project?)
    │     ├─ Agentuity native? (app.ts + @agentuity/runtime)
    │     ├─ Known framework? (25 frameworks in database)
    │     └─ Generic fallback? (package.json with build/start scripts)
    │
    ├─ 2. Build with adapter (run the framework's own build)
    │     ├─ Agentuity adapter → delegates to existing viteBundle pipeline
    │     ├─ Next.js adapter → standalone mode, asset packaging
    │     └─ Generic adapter → install deps, run build script, copy output
    │
    ├─ 3. Package output (make it deployable)
    │     ├─ launch.json → machine-readable process definitions
    │     ├─ Procfile → Heroku/Railway/Render compatible
    │     └─ .agentuity-build → build marker with framework metadata
    │
    └─ 4. Deploy (agentuity deploy only)
          ├─ Send BuildMetadata + launch info to API
          ├─ Zip build output dir → encrypt → upload
          └─ Upload static assets to CDN

Framework Detection

Detection uses a database + engine approach:

• detect/frameworks.ts — Database of 25 JS/TS framework definitions with detection rules (which packages and config files identify each framework). Rules are informed by @vercel/frameworks (Apache-2.0) but contain zero Vercel-specific properties — only generic framework facts (package names, config filenames, build commands, output directories).

• detect/engine.ts — Generic engine that evaluates detectors.every (all must match) and detectors.some (at least one must match) rules against a real project directory.

Supported frameworks (first match wins, ordered by specificity):

Category	Frameworks
Meta-frameworks	Next.js, Nuxt, Remix, React Router, SvelteKit, Astro, SolidStart, TanStack Start, RedwoodJS
Static generators	Gatsby, Eleventy, VitePress, VuePress, Docusaurus, Hexo
UI frameworks	Angular, Vue.js, Create React App, Preact
Server	Nitro
Bundlers	Vite, Parcel
Special	Agentuity native (highest priority), Generic fallback (lowest)

Build Adapters

Adapters know how to build a specific framework:

• agentuity — Delegates to the existing viteBundle() pipeline (zero behavior change for current users). Passes deployment options (ID, git info, config) through for metadata generation.
• nextjs — Enables standalone mode, packages server + static assets
• generic — Works for any framework: install deps → run build script → copy output. Injects a static file server (_serve.js) when no start command exists, so every build always produces a runnable web process.

Deploy Integration

deploy.ts now uses the same detect→adapt→package pipeline as build. Key changes:

• Agentuity native: Loads agentuity.metadata.json (from viteBundle) and attaches launch metadata
• Other frameworks: Generates BuildMetadata from BuildResult with empty routes/agents, assets from staticDir, and launch info
• Zip/upload: Uses BuildResult.outputDir instead of hardcoded .agentuity/
• CDN assets: Resolved from BuildResult.outputDir for any framework

API Contract Changes

BuildMetadataSchema (in @agentuity/core):

• routes and agents now default to [] — non-Agentuity frameworks don't have them
• New launch field (optional) containing LaunchMetadataSchema:

{
  "launch": {
    "processes": [
      { "type": "web", "command": "node server.js", "default": true }
    ],
    "framework": { "name": "nextjs", "version": "15.3.0" },
    "runtime": { "name": "node", "port": 3000 },
    "build": { "date": "2026-04-06T...", "duration": 12345 }
  }
}

Buildpack Output

Every build produces a deployment-ready directory with:

• launch.json — Process definitions (type, command, default flag), framework info, runtime info, build timestamp
• Procfile — Standard type: command format for broad PaaS compatibility
• .agentuity-build — Marker file with version, framework, runtime

Dev Command

agentuity dev is now a framework-agnostic passthrough — detects the package manager and runs <pm> run dev with PORT set.

Design Decisions

No static/server mode distinction

Every Agentuity deployment runs a process in a sandbox — there's no CDN-only tier. The mode: 'static' | 'server' concept (borrowed from Vercel's model) was removed. When a framework has no start command, the generic adapter injects a minimal Node.js static file server (_serve.js). Every build always produces a web process in launch.json.

Backwards Compatibility

Existing Agentuity native apps (app.ts + @agentuity/runtime) are detected first and routed to the agentuity adapter, which delegates to the unchanged viteBundle() pipeline. Zero behavior change for current users.

What the backend needs to do

1. Read launch.json from the deployment bundle — After extracting the zip, look for launch.json in the root. Use processes[0].command as the start command instead of hardcoding bun run app.js. Fall back to old behavior if launch.json is absent (old CLI).

2. Use runtime.name to select the runtime binary — bun for Agentuity native, node for everything else.

3. Use runtime.port for health check — Port the app listens on (defaults to 3000).

4. Don't require agentuity.metadata.json — Non-Agentuity frameworks won't produce it. The routes and agents arrays in BuildMetadata will be empty.

Tests

248 tests passing across 18 files:

File	Tests	Coverage
detect/framework-detection.test.ts	30	All framework detectors, priority ordering, combined API
detect/util.test.ts	29	File finding, dep checking, package manager detection, JSON parsing
adapters/registry.test.ts	10	Adapter lookup for all frameworks, generic fallback
package/launch.test.ts	14	Launch metadata generation, Procfile writing, build marker
buildpack-contract.test.ts	11	End-to-end: creates real projects, runs full pipeline, validates output structure

Contract tests verify static file server injection, consistent metadata across output files, and that every build produces a valid web process.

New / Modified files

packages/core/src/services/project/
└── deploy.ts              # LaunchMetadataSchema, routes/agents .default([]), launch field

packages/cli/src/
├── deploy-metadata.ts     # BuildMetadata generator for non-Agentuity frameworks
└── cmd/
    ├── build/
    │   ├── detect/
    │   │   ├── agentuity.ts      # Agentuity native detector
    │   │   ├── engine.ts          # Rule evaluation engine
    │   │   ├── frameworks.ts      # 25-framework detection database
    │   │   ├── generic.ts         # Generic fallback detector
    │   │   ├── index.ts           # Detection orchestrator
    │   │   ├── types.ts           # DetectedFramework, PackageJsonData types
    │   │   └── util.ts            # Shared utilities
    │   ├── adapters/
    │   │   ├── agentuity.ts       # Bridge to existing viteBundle pipeline
    │   │   ├── generic.ts         # Install → build → copy for any framework
    │   │   ├── nextjs.ts          # Next.js standalone mode handling
    │   │   ├── static-server.ts   # Injected file server for static builds
    │   │   ├── index.ts           # Adapter registry
    │   │   └── types.ts           # BuildAdapter, BuildResult, BuildAdapterOptions
    │   ├── package/
    │   │   ├── launch.ts          # launch.json + Procfile generation
    │   │   └── index.ts           # Output packaging orchestrator
    │   └── index.ts               # Build command (uses pipeline)
    ├── cloud/
    │   └── deploy.ts              # Deploy command (uses pipeline)
    └── dev/
        └── index.ts               # Framework-agnostic dev passthrough

[agentuity-agent]

The latest Agentuity deployment details.

Project	Deployment	Preview	Updated (UTC)
docs	🔴 Failed (deploy_43ac8471f9bb9201e2784fb0526d6a1b)	-	2026-04-06T21:18:31Z

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 919be507-56d5-412a-a388-594940f97cce

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}