@agentuity/cli 2.0.11 → 3.0.0-alpha.0

package/src/cmd/project/frameworks.ts

@@ -0,0 +1,223 @@
+/**
+ * Framework scaffolding catalog.
+ *
+ * Maps supported frameworks to their official create CLI commands
+ * and the augmentation steps needed to integrate with Agentuity.
+ *
+ * AI examples and landing pages are in separate files to keep
+ * this catalog focused on framework configuration.
+ */
+
+import {
+	nextjsAiExample,
+	nuxtAiExample,
+	remixAiExample,
+	sveltekitAiExample,
+	astroAiExample,
+	honoAiExample,
+	viteReactAiExample,
+} from './frameworks-ai-examples';
+
+import {
+	nextjsLandingPage,
+	nuxtLandingPage,
+	remixLandingPage,
+	sveltekitLandingPage,
+	astroLandingPage,
+	viteReactLandingPage,
+} from './frameworks-landing-pages';
+
+export interface FrameworkScaffold {
+	/** Unique slug (matches detect/frameworks.ts where applicable) */
+	slug: string;
+
+	/** Human-readable name */
+	name: string;
+
+	/** Short description for the select prompt */
+	description: string;
+
+	/**
+	 * Build the create command.
+	 *
+	 * @param projectDir - The target directory name (relative, e.g. "my-app")
+	 * @returns The full command as an argv array (e.g. ["bunx", "create-next-app", "my-app", ...])
+	 */
+	createCommand: (projectDir: string) => string[];
+
+	/**
+	 * Agentuity packages to add as dependencies after scaffolding.
+	 * `@agentuity/cli` is always added as a devDependency automatically.
+	 */
+	dependencies?: string[];
+
+	/**
+	 * Extra devDependencies to add (beyond @agentuity/cli).
+	 */
+	devDependencies?: string[];
+
+	/**
+	 * Scripts to merge into package.json.
+	 * These are merged on top of whatever the framework CLI created.
+	 */
+	scripts?: Record<string, string>;
+
+	/**
+	 * Generate AI SDK example files for this framework.
+	 *
+	 * Returns a map of relative file paths to file contents.
+	 * Only called if the user opts in to the AI example.
+	 */
+	aiExample?: () => Record<string, string>;
+
+	/**
+	 * Replace the framework's default landing page with an Agentuity-branded page.
+	 *
+	 * Returns a map of relative file paths to file contents.
+	 * Files overwrite the framework's default page after scaffolding.
+	 */
+	landingPage?: () => Record<string, string>;
+}
+
+// ─── Framework Catalog ───────────────────────────────────────────────────────
+
+export const frameworkCatalog: FrameworkScaffold[] = [
+	{
+		slug: 'nextjs',
+		name: 'Next.js',
+		description: 'Full-stack React framework with App Router',
+		createCommand: (dir) => [
+			'bunx',
+			'create-next-app@latest',
+			dir,
+			'--ts',
+			'--app',
+			'--tailwind',
+			'--eslint',
+			'--src-dir',
+			'--import-alias',
+			'@/*',
+			'--use-bun',
+		],
+		dependencies: ['ai', '@ai-sdk/openai'],
+		scripts: {
+			deploy: 'agentuity deploy',
+		},
+		aiExample: nextjsAiExample,
+		landingPage: nextjsLandingPage,
+	},
+	{
+		slug: 'nuxt',
+		name: 'Nuxt',
+		description: 'Full-stack Vue framework with server routes',
+		createCommand: (dir) => ['bunx', 'nuxi@latest', 'init', dir, '--packageManager', 'bun'],
+		dependencies: ['ai', '@ai-sdk/openai'],
+		scripts: {
+			deploy: 'agentuity deploy',
+		},
+		aiExample: nuxtAiExample,
+		landingPage: nuxtLandingPage,
+	},
+	{
+		slug: 'remix',
+		name: 'Remix',
+		description: 'Full-stack React framework with nested routing',
+		createCommand: (dir) => [
+			'bunx',
+			'create-remix@latest',
+			dir,
+			'--yes',
+			'--install',
+			'--package-manager',
+			'bun',
+		],
+		dependencies: ['ai', '@ai-sdk/openai'],
+		scripts: {
+			deploy: 'agentuity deploy',
+		},
+		aiExample: remixAiExample,
+		landingPage: remixLandingPage,
+	},
+	{
+		slug: 'sveltekit',
+		name: 'SvelteKit',
+		description: 'Full-stack Svelte framework',
+		createCommand: (dir) => [
+			'bunx',
+			'sv@latest',
+			'create',
+			dir,
+			'--template',
+			'minimal',
+			'--types',
+			'ts',
+		],
+		dependencies: ['ai', '@ai-sdk/openai'],
+		scripts: {
+			deploy: 'agentuity deploy',
+		},
+		aiExample: sveltekitAiExample,
+		landingPage: sveltekitLandingPage,
+	},
+	{
+		slug: 'astro',
+		name: 'Astro',
+		description: 'Content-focused framework with island architecture',
+		createCommand: (dir) => [
+			'bunx',
+			'create-astro@latest',
+			dir,
+			'--template',
+			'basics',
+			'--install',
+			'--yes',
+			'--typescript',
+			'strict',
+		],
+		dependencies: ['ai', '@ai-sdk/openai'],
+		scripts: {
+			deploy: 'agentuity deploy',
+		},
+		aiExample: astroAiExample,
+		landingPage: astroLandingPage,
+	},
+	{
+		slug: 'hono',
+		name: 'Hono',
+		description: 'Lightweight, fast web framework for the edge',
+		createCommand: (dir) => [
+			'bunx',
+			'create-hono@latest',
+			dir,
+			'--template',
+			'bun',
+			'--install',
+			'--pm',
+			'bun',
+		],
+		dependencies: ['ai', '@ai-sdk/openai'],
+		scripts: {
+			deploy: 'agentuity deploy',
+		},
+		aiExample: honoAiExample,
+	},
+	{
+		slug: 'vite-react',
+		name: 'Vite + React',
+		description: 'React SPA with Vite bundler',
+		createCommand: (dir) => ['bunx', 'create-vite@latest', dir, '--template', 'react-ts'],
+		dependencies: ['ai', '@ai-sdk/openai'],
+		scripts: {
+			deploy: 'agentuity deploy',
+		},
+		aiExample: viteReactAiExample,
+		landingPage: viteReactLandingPage,
+	},
+];
+
+/**
+ * Find a framework scaffold by slug.
+ */
+export function getFrameworkBySlug(slug: string): FrameworkScaffold | undefined {
+	return frameworkCatalog.find((f) => f.slug === slug);
+}

package/src/cmd/project/reconcile.ts

@@ -118,38 +118,28 @@ export async function getDefaultProjectName(dir: string): Promise<string> {
  * @internal Exported for testing
  */
 export async function isValidProjectStructure(dir: string): Promise<boolean> {
-	// Check 1: package.json with @agentuity/runtime and agentuity.config.ts
+	// Check 1: package.json exists (any JS/TS project is valid)
 	const pkgPath = join(dir, 'package.json');
-	const configPath = join(dir, 'agentuity.config.ts');
 
 	if (await Bun.file(pkgPath).exists()) {
 		try {
 			const pkg = await Bun.file(pkgPath).json();
-			const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-			if (deps['@agentuity/runtime'] && (await Bun.file(configPath).exists())) {
+			// Valid if it has a name and at least some structure
+			if (pkg.name || pkg.dependencies || pkg.devDependencies) {
 				return true;
 			}
 		} catch {
-			// Fall through to check child project
+			// Invalid package.json
 		}
 	}
 
-	// Check 2: ./agentuity/ subdirectory exists with valid structure (parent project with child)
+	// Check 2: ./agentuity/ subdirectory exists with a package.json (parent project with child)
 	const agentuityDir = join(dir, 'agentuity');
 	if (existsSync(agentuityDir) && statSync(agentuityDir).isDirectory()) {
 		const childPkgPath = join(agentuityDir, 'package.json');
-		const childConfigPath = join(agentuityDir, 'agentuity.config.ts');
 
 		if (await Bun.file(childPkgPath).exists()) {
-			try {
-				const childPkg = await Bun.file(childPkgPath).json();
-				const childDeps = { ...childPkg.dependencies, ...childPkg.devDependencies };
-				if (childDeps['@agentuity/runtime'] && (await Bun.file(childConfigPath).exists())) {
-					return true;
-				}
-			} catch {
-				// Invalid package.json in child - fall through
-			}
+			return true;
 		}
 	}
 
@@ -648,9 +638,8 @@ export async function reconcileProject(opts: ReconcileOptions): Promise<Reconcil
 		return {
 			status: 'error',
 			message:
-				'This directory does not appear to be a valid Agentuity project. ' +
-				'Expected agentuity.config.ts and @agentuity/runtime dependency, ' +
-				'or an agentuity/ subdirectory.',
+				'This directory does not appear to be a valid project. ' +
+				'Expected a package.json with project dependencies.',
 		};
 	}
 
@@ -743,9 +732,8 @@ export async function runProjectImport(opts: ReconcileOptions): Promise<Reconcil
 		return {
 			status: 'error',
 			message:
-				'This directory does not appear to be a valid Agentuity project. ' +
-				'Expected agentuity.config.ts and @agentuity/runtime dependency, ' +
-				'or an agentuity/ subdirectory.',
+				'This directory does not appear to be a valid project. ' +
+				'Expected a package.json with project dependencies.',
 		};
 	}
 

package/src/cmd/project/remote-import.ts

@@ -31,7 +31,7 @@ import {
 	getGithubToken,
 	linkProjectToRepo,
 } from '../git/api';
-import { initGitRepo } from './download';
+import { initGitRepo } from './scaffold';
 
 // ─── Structured Errors ───
 

package/src/cmd/project/scaffold.ts

@@ -0,0 +1,300 @@
+/**
+ * Framework scaffolding and augmentation.
+ *
+ * Replaces the old template download system. Instead of maintaining
+ * custom templates, we run the framework's official create CLI and
+ * then augment the result with Agentuity integration.
+ */
+
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Logger } from '@agentuity/core';
+import * as tui from '../../tui';
+import type { FrameworkScaffold } from './frameworks';
+
+interface ScaffoldOptions {
+	/** Absolute path to the target directory */
+	dest: string;
+	/** The directory name (for display) */
+	dirName: string;
+	/** Selected framework */
+	framework: FrameworkScaffold;
+	/** Whether to include AI example */
+	includeAiExample: boolean;
+	/** Logger */
+	logger: Logger;
+}
+
+interface SetupOptions {
+	/** Absolute path to the project directory */
+	dest: string;
+	/** Human-readable project name */
+	projectName: string;
+	/** Whether to skip `bun install` */
+	noInstall: boolean;
+	/** Logger */
+	logger: Logger;
+}
+
+/**
+ * Run the framework's official create CLI to scaffold the project.
+ */
+export async function scaffoldFramework(options: ScaffoldOptions): Promise<void> {
+	const { dest, dirName, framework, includeAiExample, logger } = options;
+
+	// Step 1: Run the framework's create command
+	const cmd = framework.createCommand(dirName);
+	logger.debug('Scaffolding with: %s', cmd.join(' '));
+
+	const parentDir = join(dest, '..');
+	mkdirSync(parentDir, { recursive: true });
+
+	const exitCode = await tui.runCommand({
+		command: `${framework.name} scaffolding`,
+		cwd: parentDir,
+		cmd,
+		clearOnSuccess: true,
+	});
+
+	if (exitCode !== 0) {
+		throw new Error(`Framework scaffolding failed (exit code ${exitCode})`);
+	}
+
+	if (!existsSync(dest)) {
+		throw new Error(`Scaffolding did not create expected directory: ${dest}`);
+	}
+
+	// Step 2: Augment with Agentuity integration
+	await augmentProject(dest, framework, includeAiExample, logger);
+}
+
+/**
+ * Augment a scaffolded project with Agentuity integration.
+ *
+ * - Adds @agentuity/cli as devDependency
+ * - Merges deploy/build scripts into package.json
+ * - Adds AI example files if requested
+ * - Generates AGENTS.md documentation
+ */
+async function augmentProject(
+	dest: string,
+	framework: FrameworkScaffold,
+	includeAiExample: boolean,
+	logger: Logger
+): Promise<void> {
+	await tui.spinner({
+		type: 'progress',
+		message: '⚡ Adding Agentuity integration...',
+		clearOnSuccess: true,
+		callback: async (progress) => {
+			// Step 1: Merge package.json
+			await mergePackageJson(dest, framework);
+			progress(40);
+
+			// Step 2: Add AI example files
+			if (includeAiExample && framework.aiExample) {
+				const files = framework.aiExample();
+				for (const [relativePath, content] of Object.entries(files)) {
+					const filePath = join(dest, relativePath);
+					const dir = join(filePath, '..');
+					mkdirSync(dir, { recursive: true });
+					await Bun.write(filePath, content);
+					logger.debug('Created AI example: %s', relativePath);
+				}
+			}
+			progress(50);
+
+			// Step 3: Replace default landing page with Agentuity-branded page
+			if (framework.landingPage) {
+				const files = framework.landingPage();
+				for (const [relativePath, content] of Object.entries(files)) {
+					const filePath = join(dest, relativePath);
+					const dir = join(filePath, '..');
+					mkdirSync(dir, { recursive: true });
+					await Bun.write(filePath, content);
+					logger.debug('Created landing page: %s', relativePath);
+				}
+			}
+			progress(75);
+
+			// Step 4: Add .gitignore entries
+			await appendGitignore(dest);
+			progress(100);
+		},
+	});
+}
+
+/**
+ * Merge Agentuity dependencies and scripts into the project's package.json.
+ */
+async function mergePackageJson(dest: string, framework: FrameworkScaffold): Promise<void> {
+	const pkgPath = join(dest, 'package.json');
+	const pkg = await Bun.file(pkgPath).json();
+
+	// Ensure sections exist
+	pkg.dependencies = pkg.dependencies ?? {};
+	pkg.devDependencies = pkg.devDependencies ?? {};
+	pkg.scripts = pkg.scripts ?? {};
+
+	// Add @agentuity/cli as devDependency
+	pkg.devDependencies['@agentuity/cli'] = 'latest';
+
+	// Add framework-specific dependencies
+	if (framework.dependencies) {
+		for (const dep of framework.dependencies) {
+			if (!pkg.dependencies[dep]) {
+				pkg.dependencies[dep] = 'latest';
+			}
+		}
+	}
+
+	// Add framework-specific devDependencies
+	if (framework.devDependencies) {
+		for (const dep of framework.devDependencies) {
+			if (!pkg.devDependencies[dep]) {
+				pkg.devDependencies[dep] = 'latest';
+			}
+		}
+	}
+
+	// Merge scripts (framework-specific scripts win)
+	if (framework.scripts) {
+		for (const [name, script] of Object.entries(framework.scripts)) {
+			pkg.scripts[name] = script;
+		}
+	}
+
+	await Bun.write(pkgPath, JSON.stringify(pkg, null, '\t') + '\n');
+}
+
+/**
+ * Append Agentuity-specific entries to .gitignore.
+ */
+async function appendGitignore(dest: string): Promise<void> {
+	const gitignorePath = join(dest, '.gitignore');
+	const entries = ['.agentuity/', '.env', '.env.local', 'agentuity.json'];
+
+	let content = '';
+	if (existsSync(gitignorePath)) {
+		content = await Bun.file(gitignorePath).text();
+	}
+
+	const missing = entries.filter((entry) => !content.includes(entry));
+	if (missing.length > 0) {
+		const section = '\n# Agentuity\n' + missing.join('\n') + '\n';
+		await Bun.write(gitignorePath, content.trimEnd() + section);
+	}
+}
+
+/**
+ * Set up the project after scaffolding: install deps, generate docs.
+ */
+export async function setupProject(options: SetupOptions): Promise<{ success: boolean }> {
+	const { dest, projectName, noInstall, logger } = options;
+	let hasError = false;
+
+	tui.info(`🔧 Setting up ${projectName}...`);
+
+	// Install dependencies (the framework CLI may have already done this,
+	// but we need to install our added deps)
+	if (!noInstall) {
+		const exitCode = await tui.runCommand({
+			command: 'bun install',
+			cwd: dest,
+			cmd: ['bun', 'install'],
+			clearOnSuccess: true,
+		});
+		if (exitCode !== 0) {
+			logger.error('Failed to install dependencies');
+			hasError = true;
+		}
+	}
+
+	return { success: !hasError };
+}
+
+// ─── Git Initialization ──────────────────────────────────────────────────────
+
+interface InitGitRepoOptions {
+	/** Project name (e.g. "My App") */
+	projectName?: string;
+	/** Where the project came from (e.g. "Next.js") */
+	source?: string;
+	/** Git commit author */
+	author?: { name: string; email: string };
+}
+
+/**
+ * Initialize a git repository and create the initial commit.
+ */
+export async function initGitRepo(dest: string, options?: InitGitRepoOptions): Promise<void> {
+	// Safety: refuse to init if .git already exists (prevents clobbering existing repos)
+	if (existsSync(join(dest, '.git'))) {
+		// Framework CLI may have already initialized git — skip
+		return;
+	}
+
+	const { isGitAvailable, getDefaultBranch } = await import('../../git-helper');
+	const gitAvailable = await isGitAvailable();
+
+	if (gitAvailable) {
+		const defaultBranch = (await getDefaultBranch()) || 'main';
+
+		await tui.runCommand({
+			command: `git init -b ${defaultBranch}`,
+			cwd: dest,
+			cmd: ['git', 'init', '-b', defaultBranch],
+			clearOnSuccess: true,
+		});
+
+		// Configure git user in CI/sandbox environments
+		if (process.env.CI || process.env.AGENTUITY_SANDBOX_ID) {
+			const cfgEmail = options?.author?.email ?? 'bot@agentuity.com';
+			const cfgName = options?.author?.name ?? 'Agentuity';
+
+			await tui.runCommand({
+				command: 'git config user.email',
+				cwd: dest,
+				cmd: ['git', 'config', 'user.email', cfgEmail],
+				clearOnSuccess: true,
+			});
+
+			await tui.runCommand({
+				command: 'git config user.name',
+				cwd: dest,
+				cmd: ['git', 'config', 'user.name', cfgName],
+				clearOnSuccess: true,
+			});
+		}
+
+		await tui.runCommand({
+			command: 'git add .',
+			cwd: dest,
+			cmd: ['git', 'add', '.'],
+			clearOnSuccess: true,
+		});
+
+		const authorName = options?.author?.name ?? 'Agentuity';
+		const authorEmail = options?.author?.email ?? 'bot@agentuity.com';
+		const authorStr = `${authorName} <${authorEmail}>`;
+
+		await tui.runCommand({
+			command: 'git commit',
+			cwd: dest,
+			cmd: [
+				'git',
+				'-c',
+				'commit.gpgsign=false',
+				'commit',
+				`--author=${authorStr}`,
+				'-m',
+				'Initial Setup',
+			],
+			env: {
+				GIT_COMMITTER_NAME: authorName,
+				GIT_COMMITTER_EMAIL: authorEmail,
+			},
+			clearOnSuccess: true,
+		});
+	}
+}