@agentuity/cli 2.0.10 → 3.0.0-alpha.0

package/src/cmd/build/detect/index.ts

@@ -0,0 +1,122 @@
+/**
+ * Framework Detection
+ *
+ * Examines a project directory and determines which JS framework is being used.
+ * Returns a DetectedFramework with all the information needed to build and launch.
+ *
+ * Detection strategy:
+ * 1. Run the framework database engine (rules derived from @vercel/frameworks)
+ * 2. Fall back to generic detection (package.json scripts)
+ */
+
+import type { DetectedFramework, PackageJsonData } from './types';
+import { readPackageJson, detectPackageManager } from './util';
+import { frameworkDefinitions } from './frameworks';
+import { detectFromDatabase } from './engine';
+import { genericDetector } from './generic';
+
+/**
+ * Convert a matched framework definition + project context into a DetectedFramework.
+ */
+async function frameworkDefToDetected(
+	slug: string,
+	_name: string,
+	buildCommand: string | null,
+	outputDirectory: string | null,
+	staticDirectory: string | null | undefined,
+	projectDir: string,
+	pkg: PackageJsonData
+): Promise<DetectedFramework> {
+	const pm = await detectPackageManager(projectDir);
+
+	// Use the project's build script if available, otherwise the framework default
+	const resolvedBuildCommand = pkg.scripts?.build ?? buildCommand ?? 'npm run build';
+
+	// Resolve output directory — use framework default or '.'
+	const resolvedOutputDir = outputDirectory ?? '.';
+
+	// Resolve static asset directory (relative to project root):
+	// - explicit string: path relative to project root (e.g., '.next/static', '.output/public')
+	// - null: the entire output directory is static (SSGs, SPAs) — use outputDirectory
+	// - undefined: no static assets known for this framework
+	const resolvedStaticDir =
+		staticDirectory === null
+			? resolvedOutputDir // null means entire output IS the static dir
+			: (staticDirectory ?? undefined);
+
+	return {
+		name: slug,
+		runtime: 'node',
+		packageManager: pm,
+		buildCommand: resolvedBuildCommand,
+		buildOutput: resolvedOutputDir,
+		staticDir: resolvedStaticDir,
+		confidence: 'high',
+	};
+}
+
+/**
+ * Detect the framework used by a project.
+ *
+ * @param projectDir - Absolute path to the project root
+ * @returns DetectedFramework or null if nothing could be detected
+ */
+export async function detectFramework(projectDir: string): Promise<DetectedFramework | null> {
+	const pkg = await readPackageJson(projectDir);
+	if (!pkg) return null;
+
+	// 1. Run through the framework database
+	const match = await detectFromDatabase(projectDir, pkg, frameworkDefinitions);
+	if (match) {
+		return frameworkDefToDetected(
+			match.slug,
+			match.name,
+			match.buildCommand,
+			match.outputDirectory,
+			match.staticDir,
+			projectDir,
+			pkg
+		);
+	}
+
+	// 2. Generic fallback
+	return genericDetector.detect(projectDir, pkg);
+}
+
+/**
+ * Detect the framework, but also return the parsed package.json for reuse.
+ */
+export async function detectFrameworkWithPackageJson(
+	projectDir: string
+): Promise<{ framework: DetectedFramework | null; packageJson: PackageJsonData | null }> {
+	const pkg = await readPackageJson(projectDir);
+	if (!pkg) return { framework: null, packageJson: null };
+
+	// 1. Run through the framework database
+	const match = await detectFromDatabase(projectDir, pkg, frameworkDefinitions);
+	if (match) {
+		const framework = await frameworkDefToDetected(
+			match.slug,
+			match.name,
+			match.buildCommand,
+			match.outputDirectory,
+			match.staticDir,
+			projectDir,
+			pkg
+		);
+		return { framework, packageJson: pkg };
+	}
+
+	// 2. Generic fallback
+	const generic = await genericDetector.detect(projectDir, pkg);
+	return { framework: generic, packageJson: pkg };
+}
+
+// Re-export types
+export type {
+	DetectedFramework,
+	FrameworkName,
+	PackageJsonData,
+	PackageManager,
+	RuntimeName,
+} from './types';

package/src/cmd/build/detect/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Framework detection types.
+ *
+ * These types define the contract between detection, adapters, and packaging.
+ * The detection system identifies what JS framework a project uses,
+ * and adapters know how to build and launch each framework.
+ */
+
+/**
+ * Framework identifier.
+ *
+ * This is a string rather than a union type because the framework database
+ * (derived from @vercel/frameworks) contains 25+ slugs and may grow.
+ * Special values:
+ * - 'generic' — Fallback: has package.json with build/start scripts
+ */
+export type FrameworkName = string;
+
+/**
+ * Runtime that executes the built application.
+ */
+export type RuntimeName = 'node' | 'bun';
+
+/**
+ * Package manager detected or preferred.
+ */
+export type PackageManager = 'bun' | 'npm' | 'pnpm' | 'yarn';
+
+/**
+ * Result of framework detection.
+ *
+ * This is the output of the detect phase and input to the adapter/build phase.
+ */
+export interface DetectedFramework {
+	/** Framework identifier */
+	name: FrameworkName;
+
+	/** Human-readable framework version (e.g., "15.3.0" for Next.js) */
+	version?: string;
+
+	/** Runtime that runs the production server */
+	runtime: RuntimeName;
+
+	/** Detected package manager */
+	packageManager: PackageManager;
+
+	/** The build command to execute (e.g., "next build", "vite build") */
+	buildCommand: string;
+
+	/** Directory where build output is written (relative to project root) */
+	buildOutput: string;
+
+	/** Command to start the production server (only for mode='server') */
+	startCommand?: string;
+
+	/** Server entrypoint file (relative to buildOutput) */
+	serverEntry?: string;
+
+	/**
+	 * Static/CDN asset directory (relative to project root).
+	 * After the build runs, this directory contains files suitable for CDN upload.
+	 * For pure SSGs/SPAs this equals buildOutput (entire output is static).
+	 * For SSR frameworks this is a subdirectory (e.g., `.next/static`, `.output/public`).
+	 */
+	staticDir?: string;
+
+	/** Environment variables needed at build time */
+	buildEnv?: Record<string, string>;
+
+	/** Port the app listens on (default: 3000) */
+	port?: number;
+
+	/** Detection confidence: 'high' if config file found, 'low' if inferred */
+	confidence: 'high' | 'medium' | 'low';
+}
+
+/**
+ * A single framework detector.
+ *
+ * Each detector examines the project directory and returns a DetectedFramework
+ * if it recognizes the project, or null if it doesn't apply.
+ */
+export interface FrameworkDetector {
+	/** Framework this detector handles */
+	name: FrameworkName;
+
+	/** Priority (lower = checked first). Specific frameworks before generic. */
+	priority: number;
+
+	/**
+	 * Examine the project and return detection result, or null if not applicable.
+	 */
+	detect(projectDir: string, packageJson: PackageJsonData): Promise<DetectedFramework | null>;
+}
+
+/**
+ * Parsed package.json data relevant to detection.
+ */
+export interface PackageJsonData {
+	name?: string;
+	version?: string;
+	scripts?: Record<string, string>;
+	dependencies?: Record<string, string>;
+	devDependencies?: Record<string, string>;
+	main?: string;
+	module?: string;
+	type?: string;
+	engines?: Record<string, string>;
+}

package/src/cmd/build/detect/util.ts

@@ -0,0 +1,104 @@
+/**
+ * Detection utilities shared across framework detectors.
+ */
+
+import { join } from 'node:path';
+import type { PackageJsonData, PackageManager } from './types';
+
+/**
+ * Check if a file exists (any of the given names) in a directory.
+ * Returns the first matching filename, or null.
+ */
+export async function findFile(dir: string, names: string[]): Promise<string | null> {
+	for (const name of names) {
+		const file = Bun.file(join(dir, name));
+		if (await file.exists()) {
+			return name;
+		}
+	}
+	return null;
+}
+
+/**
+ * Check if a dependency exists in package.json (dependencies or devDependencies).
+ */
+export function hasDependency(pkg: PackageJsonData, name: string): boolean {
+	return !!(pkg.dependencies?.[name] || pkg.devDependencies?.[name]);
+}
+
+/**
+ * Get the version of a dependency from package.json.
+ * Returns the version range string, or null if not found.
+ */
+export function getDependencyVersion(pkg: PackageJsonData, name: string): string | null {
+	return pkg.dependencies?.[name] ?? pkg.devDependencies?.[name] ?? null;
+}
+
+/**
+ * Check if any dependency matching a pattern exists.
+ */
+export function hasDependencyMatching(pkg: PackageJsonData, pattern: RegExp): boolean {
+	const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+	return Object.keys(allDeps).some((name) => pattern.test(name));
+}
+
+/**
+ * Detect which package manager the project uses by checking lockfiles.
+ */
+export async function detectPackageManager(projectDir: string): Promise<PackageManager> {
+	if (await Bun.file(join(projectDir, 'bun.lockb')).exists()) return 'bun';
+	if (await Bun.file(join(projectDir, 'bun.lock')).exists()) return 'bun';
+	if (await Bun.file(join(projectDir, 'pnpm-lock.yaml')).exists()) return 'pnpm';
+	if (await Bun.file(join(projectDir, 'yarn.lock')).exists()) return 'yarn';
+	if (await Bun.file(join(projectDir, 'package-lock.json')).exists()) return 'npm';
+
+	// Default to bun (our preferred runtime)
+	return 'bun';
+}
+
+/**
+ * Get the run command prefix for a package manager.
+ * e.g., 'npm run', 'bun run', 'pnpm run', 'yarn'
+ */
+export function getRunCommand(pm: PackageManager): string {
+	switch (pm) {
+		case 'bun':
+			return 'bun run';
+		case 'npm':
+			return 'npm run';
+		case 'pnpm':
+			return 'pnpm run';
+		case 'yarn':
+			return 'yarn';
+	}
+}
+
+/**
+ * Get the exec command prefix for a package manager (npx/bunx/etc.).
+ */
+export function getExecCommand(pm: PackageManager): string {
+	switch (pm) {
+		case 'bun':
+			return 'bunx';
+		case 'npm':
+			return 'npx';
+		case 'pnpm':
+			return 'pnpm exec';
+		case 'yarn':
+			return 'yarn dlx';
+	}
+}
+
+/**
+ * Read and parse package.json from a directory.
+ * Returns null if not found or unparseable.
+ */
+export async function readPackageJson(dir: string): Promise<PackageJsonData | null> {
+	const file = Bun.file(join(dir, 'package.json'));
+	if (!(await file.exists())) return null;
+	try {
+		return (await file.json()) as PackageJsonData;
+	} catch {
+		return null;
+	}
+}

package/src/cmd/build/index.ts

@@ -1,13 +1,14 @@
 import { z } from 'zod';
 import { resolve, join, relative } from 'node:path';
 import { createCommand, DeployOptionsSchema } from '../../types';
-import { viteBundle } from './vite-bundler';
 import * as tui from '../../tui';
 import { getCommand } from '../../command-prefix';
 import { ErrorCode } from '../../errors';
 import { typecheck } from './typecheck';
 import { BuildReportCollector, setGlobalCollector, clearGlobalCollector } from '../../build-report';
-import { detectVersionMismatch, formatVersionMismatchWarning } from '../../utils/version-mismatch';
+import { detectFrameworkWithPackageJson } from './detect';
+import { getAdapter } from './adapters';
+import { packageBuildOutput } from './package';
 
 const BuildResponseSchema = z.object({
 	success: z.boolean().describe('Whether the build succeeded'),
@@ -15,6 +16,7 @@ const BuildResponseSchema = z.object({
 	projectName: z.string().describe('Project name'),
 	dev: z.boolean().describe('Whether dev mode was enabled'),
 	size: z.number().optional().describe('Build size in bytes'),
+	framework: z.string().optional().describe('Detected framework name'),
 });
 
 const BuildOptionsSchema = z.intersection(
@@ -58,6 +60,10 @@ export const command = createCommand({
 		const { opts, projectDir, project } = ctx;
 
 		if (opts.ci) {
+			if (!opts.url) {
+				tui.fatal('--url is required when using --ci mode', ErrorCode.CONFIG_INVALID);
+			}
+
 			const { runCIBuild } = await import('./ci');
 			await runCIBuild(
 				{
@@ -95,37 +101,72 @@ export const command = createCommand({
 		}
 
 		const absoluteProjectDir = resolve(projectDir);
-
-		// Check for version mismatches (v1 vs v2 SDK packages)
-		const versionMismatch = detectVersionMismatch(absoluteProjectDir, ctx.logger);
-		if (versionMismatch.hasV1Packages || versionMismatch.hasMajorMismatches) {
-			tui.newline();
-			tui.warning(formatVersionMismatchWarning(versionMismatch));
-			tui.newline();
-		}
-
 		const outDir = opts.outdir ? resolve(opts.outdir) : join(absoluteProjectDir, '.agentuity');
 
 		try {
 			const rel = outDir.startsWith(absoluteProjectDir)
 				? relative(absoluteProjectDir, outDir)
 				: outDir;
-			tui.info(`Building project with Vite at ${absoluteProjectDir} to ${rel}`);
 
-			await viteBundle({
-				rootDir: absoluteProjectDir,
-				dev: opts.dev || false,
+			// Step 1: Detect framework
+			tui.info('Detecting framework...');
+			const { framework, packageJson } =
+				await detectFrameworkWithPackageJson(absoluteProjectDir);
+
+			if (!framework) {
+				collector.addGeneralError(
+					'build',
+					'Could not detect a JS framework. Ensure package.json exists with a build script.',
+					'BUILD010'
+				);
+				if (opts.reportFile) {
+					await collector.forceWrite();
+				}
+				clearGlobalCollector();
+				tui.fatal(
+					'Could not detect a JS framework. Ensure package.json exists with a build script.',
+					ErrorCode.BUILD_FAILED
+				);
+			}
+
+			const frameworkLabel = framework.version
+				? `${framework.name} v${framework.version}`
+				: framework.name;
+			tui.success(`Detected ${tui.bold(frameworkLabel)} (${framework.runtime})`);
+
+			// Step 2: Get the build adapter for this framework
+			const adapter = getAdapter(framework.name);
+			tui.info(`Building with ${adapter.name} adapter to ${rel}`);
+
+			// Step 3: Run the build
+			const endBuildDiagnostic = collector.startDiagnostic('build');
+			const buildResult = await adapter.build({
+				projectDir: absoluteProjectDir,
+				framework,
+				packageJson: packageJson!,
+				outputDir: outDir,
+				logger: ctx.logger,
+				collector,
+				dev: opts.dev,
 				projectId: project?.projectId,
 				orgId: project?.orgId,
 				region: project?.region ?? 'local',
-				logger: ctx.logger,
-				collector,
 			});
+			endBuildDiagnostic();
+
+			// Log build output
+			for (const line of buildResult.logs) {
+				tui.info(tui.muted(line));
+			}
+
+			// Step 4: Package the output with launch metadata
+			const packageResult = packageBuildOutput(framework, buildResult, buildResult.outputDir);
+			ctx.logger.debug('Launch metadata: %s', JSON.stringify(packageResult.launch, null, 2));
 
-			// Copy profile-specific .env file AFTER bundling (bundler clears outDir first)
+			// Step 5: Copy profile-specific .env file AFTER building
 			if (opts.dev && ctx.config?.name) {
 				const envSourcePath = join(absoluteProjectDir, `.env.${ctx.config.name}`);
-				const envDestPath = join(outDir, '.env');
+				const envDestPath = join(buildResult.outputDir, '.env');
 
 				const envFile = Bun.file(envSourcePath);
 				if (await envFile.exists()) {
@@ -136,7 +177,7 @@ export const command = createCommand({
 				}
 			}
 
-			// Run TypeScript type checking after registry generation (skip in dev mode)
+			// Step 6: Run TypeScript type checking (skip in dev mode, skip for non-TS projects)
 			if (!opts.dev && !opts.skipTypeCheck) {
 				try {
 					tui.info('Running type check...');
@@ -153,7 +194,6 @@ export const command = createCommand({
 						const msg =
 							'errors' in typeResult ? 'Fix type errors before building' : 'Build error';
 
-						// Write report before fatal exit
 						if (opts.reportFile) {
 							await collector.forceWrite();
 						}
@@ -164,7 +204,6 @@ export const command = createCommand({
 					const errorMsg = error instanceof Error ? error.message : String(error);
 					collector.addGeneralError('typescript', errorMsg, 'BUILD008');
 
-					// Write report before fatal exit
 					if (opts.reportFile) {
 						await collector.forceWrite();
 					}
@@ -178,7 +217,7 @@ export const command = createCommand({
 				}
 			}
 
-			tui.success('Build complete');
+			tui.success(`Build complete (${frameworkLabel}, ${buildResult.duration}ms)`);
 
 			// Write final report on success
 			if (opts.reportFile) {
@@ -188,9 +227,10 @@ export const command = createCommand({
 
 			return {
 				success: true,
-				bundlePath: outDir,
+				bundlePath: buildResult.outputDir,
 				projectName: project?.projectId || 'unknown',
 				dev: opts.dev || false,
+				framework: framework.name,
 			};
 		} catch (error: unknown) {
 			// Add error to collector

package/src/cmd/build/package/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Build output packaging.
+ *
+ * After a framework adapter builds the project, the packager:
+ * 1. Generates launch metadata (how to start the app)
+ * 2. Writes a Procfile for compatibility
+ * 3. Optionally generates additional metadata
+ *
+ * The output is a self-contained directory ready for deployment
+ * as a buildpack image layer or traditional zip upload.
+ */
+
+import { join } from 'node:path';
+import { writeFileSync } from 'node:fs';
+import type { DetectedFramework } from '../detect/types';
+import type { BuildResult } from '../adapters/types';
+import { generateLaunchMetadata, writeLaunchMetadata, type LaunchMetadata } from './launch';
+
+export interface PackageResult {
+	/** Absolute path to the packaged output */
+	outputDir: string;
+
+	/** Launch metadata */
+	launch: LaunchMetadata;
+
+	/** Whether the output contains static assets */
+	hasStaticAssets: boolean;
+
+	/** Path to static assets (if any) */
+	staticDir?: string;
+}
+
+/**
+ * Package a build result into a deployment-ready directory.
+ */
+export function packageBuildOutput(
+	framework: DetectedFramework,
+	buildResult: BuildResult,
+	outputDir: string
+): PackageResult {
+	// Generate launch metadata
+	const launch = generateLaunchMetadata(framework, buildResult);
+
+	// Write launch metadata to the output directory
+	writeLaunchMetadata(outputDir, launch);
+
+	// Write a .buildpack-ready marker file
+	const markerPath = join(outputDir, '.agentuity-build');
+	const markerContent = {
+		version: 1,
+		framework: framework.name,
+		runtime: framework.runtime,
+		buildDate: new Date().toISOString(),
+	};
+	writeFileSync(markerPath, JSON.stringify(markerContent, null, 2), 'utf-8');
+
+	return {
+		outputDir,
+		launch,
+		hasStaticAssets: !!buildResult.staticDir,
+		staticDir: buildResult.staticDir,
+	};
+}
+
+// Re-export
+export type { LaunchMetadata, ProcessDefinition } from './launch';

package/src/cmd/build/package/launch.ts

@@ -0,0 +1,104 @@
+/**
+ * Launch metadata generation for buildpack-compatible output.
+ *
+ * Generates the metadata that tells the runtime how to start the application.
+ * This is analogous to CNB's launch.toml / Procfile / Docker CMD.
+ */
+
+import { join } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import type { BuildResult } from '../adapters/types';
+import type { DetectedFramework } from '../detect/types';
+
+/**
+ * Process definition for the launch metadata.
+ */
+export interface ProcessDefinition {
+	/** Process type (e.g., 'web', 'worker') */
+	type: string;
+	/** Command to execute */
+	command: string;
+	/** Whether this is the default process */
+	default: boolean;
+	/** Working directory (relative to app root) */
+	workingDirectory?: string;
+}
+
+/**
+ * Complete launch metadata written to the output directory.
+ */
+export interface LaunchMetadata {
+	/** Application processes */
+	processes: ProcessDefinition[];
+	/** Framework that was detected */
+	framework: {
+		name: string;
+		version?: string;
+	};
+	/** Runtime information */
+	runtime: {
+		name: string;
+		port?: number;
+	};
+	/** Build information */
+	build: {
+		date: string;
+		duration: number;
+	};
+}
+
+/**
+ * Generate launch metadata from a build result and detected framework.
+ */
+export function generateLaunchMetadata(
+	framework: DetectedFramework,
+	buildResult: BuildResult
+): LaunchMetadata {
+	const processes: ProcessDefinition[] = [];
+
+	// Primary web process
+	const startCommand = buildResult.startCommand ?? framework.startCommand;
+	if (startCommand) {
+		processes.push({
+			type: 'web',
+			command: startCommand,
+			default: true,
+		});
+	}
+
+	return {
+		processes,
+		framework: {
+			name: framework.name,
+			version: framework.version,
+		},
+		runtime: {
+			name: framework.runtime,
+			port: buildResult.port ?? framework.port,
+		},
+		build: {
+			date: new Date().toISOString(),
+			duration: buildResult.duration,
+		},
+	};
+}
+
+/**
+ * Write launch metadata to the output directory.
+ *
+ * Writes both:
+ * - launch.json — machine-readable launch metadata
+ * - Procfile — simple process definition for compatibility
+ */
+export function writeLaunchMetadata(outputDir: string, metadata: LaunchMetadata): void {
+	mkdirSync(outputDir, { recursive: true });
+
+	// Write JSON metadata
+	const jsonPath = join(outputDir, 'launch.json');
+	writeFileSync(jsonPath, JSON.stringify(metadata, null, 2), 'utf-8');
+
+	// Write Procfile for broad compatibility (Heroku, Railway, Render, etc.)
+	const procfilePath = join(outputDir, 'Procfile');
+	const procfileLines = metadata.processes.map((p) => `${p.type}: ${p.command}`);
+	writeFileSync(procfilePath, procfileLines.join('\n') + '\n', 'utf-8');
+}

package/src/cmd/build/typecheck.ts

@@ -1,3 +1,4 @@
+import { join } from 'node:path';
 import { parse, type GrammarItem } from '../../tsc-output-parser';
 import { formatTypeScriptErrors, hasErrors } from '../../typescript-errors';
 import type { BuildReportCollector } from '../../build-report';
@@ -73,6 +74,14 @@ function filterNodeModulesErrors(output: string): string {
  * @returns
  */
 export async function typecheck(dir: string, options?: TypecheckOptions): Promise<TypeResult> {
+	// Skip typecheck for projects without tsconfig.json (plain JS projects)
+	const tsconfigPath = join(dir, 'tsconfig.json');
+	const tsconfigFile = Bun.file(tsconfigPath);
+	const tsconfigExists = await tsconfigFile.exists();
+	if (!tsconfigExists) {
+		return { success: true };
+	}
+
 	const { collector } = options ?? {};
 	const result = await Bun.$`bunx tsc --noEmit --skipLibCheck --pretty false`
 		.cwd(dir)