@alexanderolsen/create-deepagent 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/index.js

@@ -0,0 +1,661 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import * as clack from "@clack/prompts";
+import { spinner } from "@clack/prompts";
+import pc from "picocolors";
+import { MODEL_PROVIDER_CONFIG } from "langchain/chat_models/universal";
+import { inspect } from "node:util";
+import { execSync } from "node:child_process";
+import os from "node:os";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { x } from "tar";
+//#region src/utils/logger.ts
+const logger = {
+	info: (msg) => console.log(pc.cyan(msg)),
+	success: (msg) => console.log(pc.green(msg)),
+	warn: (msg) => console.log(pc.yellow(msg)),
+	error: (msg) => console.error(pc.red(msg)),
+	break: () => console.log(),
+	step: (msg) => console.log(pc.dim("›") + " " + msg)
+};
+//#endregion
+//#region src/utils/validate.ts
+/** Check if a path exists and is a directory. */
+async function dirExists(dir) {
+	try {
+		return (await fs.promises.stat(dir)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/** Check if an existing directory is empty. Throws if the dir cannot be read. */
+async function isDirEmpty(dir) {
+	return (await fs.promises.readdir(dir)).length === 0;
+}
+/** Check if a directory is writable. */
+async function isWriteable(dir) {
+	try {
+		await fs.promises.access(dir, fs.constants.W_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Ensure a directory exists, creating it if necessary. */
+async function makeDir(dir) {
+	await fs.promises.mkdir(dir, { recursive: true });
+}
+/** Validate a npm package name. Returns an error message or null if valid. */
+function validatePkgName(name) {
+	if (!name) return "Project name is required";
+	if (name.length > 214) return "Project name must be 214 characters or less";
+	if (name.startsWith(".") || name.startsWith("_")) return "Project name must not start with . or _";
+	if (name.toLowerCase() !== name) return "Project name must be lowercase";
+	if (/\s/.test(name)) return "Project name must not contain spaces";
+	if (!/^[a-z0-9._-]+$/.test(name)) return "Project name may only contain lowercase letters, numbers, ., _, and -";
+	return null;
+}
+//#endregion
+//#region src/commands/create/preflightCreate.ts
+/**
+* Post-TUI checks before scaffolding. Fails fast on:
+* - Invalid package name
+* - Target directory not empty (unless --force or user confirms)
+* - Target directory not writable
+*/
+async function preflightCreate(options) {
+	const { projectName, force } = options;
+	const nameErr = validatePkgName(projectName);
+	if (nameErr) {
+		logger.error(nameErr);
+		process.exit(1);
+	}
+	const projectPath = path.resolve(projectName);
+	if (await dirExists(projectPath) && !force) {
+		if (!await isDirEmpty(projectPath)) {
+			const proceed = await clack.confirm({
+				message: `Directory "${projectName}" is not empty. Continue anyway?`,
+				initialValue: false
+			});
+			if (clack.isCancel(proceed) || proceed === false) {
+				clack.cancel("Cancelled, exiting...");
+				process.exit(0);
+			}
+		}
+	}
+	if (!await isWriteable(path.dirname(projectPath))) {
+		logger.error(`Cannot write to ${path.dirname(projectPath)}`);
+		process.exit(1);
+	}
+	return projectPath;
+}
+//#endregion
+//#region src/registry/provider.ts
+function createProvider(config) {
+	return {
+		...config,
+		dependency: MODEL_PROVIDER_CONFIG[config.id].package,
+		chatModelClassName: MODEL_PROVIDER_CONFIG[config.id].className
+	};
+}
+//#endregion
+//#region src/registry/files/model.ts
+/**
+* Create a ProviderAwareFile for `model.ts` that exports `coordinatorModel` and
+* `subagentModel`, instantiated via direct constructor imports with the selected
+* provider.
+*
+* @param agentPath - Path relative to project root, e.g. "lib/agent"
+*/
+function createModelFile(agentPath) {
+	return {
+		path: `${agentPath}/model.ts`,
+		getContent: ({ providerConfig }) => {
+			const { defaultModel, coordinatorModelConfig, dependency, chatModelClassName } = providerConfig;
+			const coordinatorOptions = {
+				model: defaultModel,
+				...coordinatorModelConfig ?? {}
+			};
+			return [
+				`import { ${chatModelClassName} } from "${dependency}";`,
+				"",
+				`const coordinatorModel = new ${chatModelClassName}(${inspect(coordinatorOptions, {
+					depth: null,
+					compact: false
+				})});`,
+				"",
+				`const subagentModel = new ${chatModelClassName}(${inspect({ model: defaultModel }, {
+					depth: null,
+					compact: false
+				})});`,
+				"",
+				"export { coordinatorModel, subagentModel };"
+			].join("\n") + "\n";
+		}
+	};
+}
+//#endregion
+//#region src/registry/files/envExample.ts
+/**
+* Create a ProviderAwareFile for `.env.example` with the provider's env var
+* names and commented-out LangSmith tracing lines.
+*/
+function createEnvExampleFile() {
+	return {
+		path: ".env.example",
+		getContent: ({ providerConfig }) => {
+			const { env } = providerConfig;
+			const lines = [];
+			for (const spec of env) {
+				const label = spec.prompt ?? spec.name;
+				lines.push(`# Required: ${label} used by the agent and its subagents.`);
+				lines.push(`${spec.name}=`);
+			}
+			lines.push("");
+			lines.push("# Optional: enable LangSmith tracing.");
+			lines.push("# LANGSMITH_TRACING=true");
+			lines.push("# LANGSMITH_API_KEY=lsv2-...");
+			return lines.join("\n") + "\n";
+		}
+	};
+}
+//#endregion
+//#region src/registry/framework.ts
+function createFramework(config) {
+	const defaultFiles = [createModelFile(config.agentPath), createEnvExampleFile()];
+	return {
+		...config,
+		files: [...config.files, ...defaultFiles]
+	};
+}
+//#endregion
+//#region registry/providers/openai.ts
+const openai = createProvider({
+	id: "openai",
+	title: "OpenAI",
+	defaultModel: "gpt-5.4-mini",
+	coordinatorModelConfig: { reasoning: {
+		effort: "low",
+		summary: "auto"
+	} },
+	env: [{
+		name: "OPENAI_API_KEY",
+		prompt: "OpenAI API key",
+		required: false
+	}]
+});
+//#endregion
+//#region registry/providers/anthropic.ts
+const anthropic = createProvider({
+	id: "anthropic",
+	title: "Anthropic",
+	defaultModel: "claude-sonnet-4-5-20250929",
+	env: [{
+		name: "ANTHROPIC_API_KEY",
+		prompt: "Anthropic API key",
+		required: false
+	}]
+});
+//#endregion
+//#region registry/providers/google.ts
+const google = createProvider({
+	id: "google-genai",
+	title: "Google",
+	defaultModel: "gemini-3.5-flash",
+	env: [{
+		name: "GOOGLE_API_KEY",
+		prompt: "Google API key",
+		required: false
+	}]
+});
+//#endregion
+//#region registry/providers/fireworks.ts
+const fireworks = createProvider({
+	id: "fireworks",
+	title: "Fireworks",
+	defaultModel: "accounts/fireworks/models/glm-5p1",
+	env: [{
+		name: "FIREWORKS_API_KEY",
+		prompt: "Fireworks API key",
+		required: false
+	}]
+});
+//#endregion
+//#region registry/frameworks/next.ts
+const next = createFramework({
+	id: "next",
+	title: "Next.js",
+	defaultProjectName: "next-deepagents",
+	address: {
+		scheme: "github",
+		owner: "aolsenjazz",
+		repo: "deployment-cookbook",
+		subPath: "js-next"
+	},
+	envFilePath: ".env.local",
+	packageJsonPath: "package.json",
+	agentPath: "lib/agent",
+	files: []
+});
+//#endregion
+//#region registry/frameworks/nuxt.ts
+const nuxt = createFramework({
+	id: "nuxt",
+	title: "Nuxt",
+	defaultProjectName: "nuxt-deepagents",
+	address: {
+		scheme: "github",
+		owner: "aolsenjazz",
+		repo: "deployment-cookbook",
+		subPath: "js-nuxt"
+	},
+	envFilePath: ".env",
+	packageJsonPath: "package.json",
+	agentPath: "server/agent",
+	files: []
+});
+const hono = createFramework({
+	id: "hono",
+	title: "Hono",
+	defaultProjectName: "hono-deepagents",
+	address: {
+		scheme: "github",
+		owner: "aolsenjazz",
+		repo: "deployment-cookbook",
+		subPath: "js-cloudflare"
+	},
+	envFilePath: ".env",
+	packageJsonPath: "package.json",
+	agentPath: "worker/agent",
+	files: [{
+		path: "worker/env.d.ts",
+		getContent: ({ providerConfig }) => {
+			return `interface Env {
+  ASSETS: Fetcher;
+  SESSIONS: DurableObjectNamespace;
+${providerConfig.env.map((e) => `  ${e.name}: string;`).join("\n")}
+  [key: string]: string | undefined;
+}
+`;
+		}
+	}]
+});
+//#endregion
+//#region registry/frameworks/deno.ts
+const deno = createFramework({
+	id: "deno",
+	title: "Deno",
+	defaultProjectName: "deno-deepagents",
+	address: {
+		scheme: "github",
+		owner: "aolsenjazz",
+		repo: "deployment-cookbook",
+		subPath: "js-deno"
+	},
+	envFilePath: ".env",
+	packageJsonPath: "package.json",
+	agentPath: "server/agent",
+	files: []
+});
+//#endregion
+//#region registry/frameworks/vite.ts
+const vite = createFramework({
+	id: "react-vite",
+	title: "React + Vite",
+	defaultProjectName: "react-deepagents",
+	address: {
+		scheme: "github",
+		owner: "aolsenjazz",
+		repo: "deployment-cookbook",
+		subPath: "js-langsmith"
+	},
+	envFilePath: ".env",
+	packageJsonPath: "package.json",
+	agentPath: "agent",
+	files: []
+});
+//#endregion
+//#region src/registry/index.ts
+const providers = {
+	[openai.id]: openai,
+	[anthropic.id]: anthropic,
+	[google.id]: google,
+	[fireworks.id]: fireworks
+};
+const frameworks = {
+	[next.id]: next,
+	[nuxt.id]: nuxt,
+	[hono.id]: hono,
+	[vite.id]: vite,
+	[deno.id]: deno
+};
+//#endregion
+//#region src/commands/create/runCreateConfig.ts
+const PROCESSS_EXIT_MESSAGE = "Cancelled, exiting...";
+/**
+* Guides the user through the config TUI. On SIGINT, either moves to the next
+* step or kills the process via `process.kill(0)`
+*/
+async function runCreateConfig() {
+	clack.intro("create-deepagent");
+	const frameworkConfig = await selectFramework();
+	const providerConfig = await selectProvider();
+	const envVars = await collectEnvVars(providerConfig, frameworkConfig);
+	const tracing = await selectTracing() ?? false;
+	const langSmithKey = await collectLangSmithKey(tracing, frameworkConfig);
+	return {
+		frameworkChoice: frameworkConfig.id,
+		providerChoice: providerConfig.id,
+		envVars,
+		tracing,
+		langSmithKey
+	};
+}
+/** Prompt a user to select their framework */
+async function selectFramework() {
+	const frameworkOptions = Object.values(frameworks).map((f) => ({
+		value: f.id,
+		label: f.title
+	}));
+	const frameworkChoice = await clack.select({
+		message: "Select your framework",
+		options: frameworkOptions
+	});
+	if (clack.isCancel(frameworkChoice)) {
+		clack.cancel(PROCESSS_EXIT_MESSAGE);
+		process.exit(0);
+	}
+	const framework = frameworks[frameworkChoice];
+	if (!framework) throw new Error(`Framework "${frameworkChoice}" not found`);
+	return framework;
+}
+/** Prompt a user to select their provider */
+async function selectProvider() {
+	const providerOptions = Object.values(providers).map((p) => ({
+		value: p.id,
+		label: p.title
+	}));
+	const providerChoice = await clack.select({
+		message: "Select your provider",
+		options: providerOptions
+	});
+	if (clack.isCancel(providerChoice)) {
+		clack.cancel(PROCESSS_EXIT_MESSAGE);
+		process.exit(0);
+	}
+	const provider = providers[providerChoice];
+	if (!provider) throw new Error(`Provider "${providerChoice}" not found`);
+	return provider;
+}
+/** Prompt the user to enter env vars as are required by the provider spec */
+async function collectEnvVars(provider, framework) {
+	const envVars = {};
+	for (const spec of provider.env) {
+		const optionalExitMessage = `Skipping ${spec.prompt}. You can add this later in ${framework.envFilePath}`;
+		const result = await clack.password({
+			message: `Enter ${spec.prompt ?? spec.name}${!spec.required && " (press enter to skip)?"}`,
+			mask: "*",
+			validate: (value) => {
+				if (typeof value !== "string" && spec.required === true) return `${spec.name} must not be empty.`;
+				if (value?.trim().length === 0) return `Invalid ${spec.name}. Try again.`;
+			}
+		});
+		const resultString = typeof result === "string" && result.trim() ? result.trim() : void 0;
+		if (clack.isCancel(result) || resultString === void 0) {
+			if (spec.required) {
+				clack.cancel(PROCESSS_EXIT_MESSAGE);
+				process.exit(0);
+			}
+			clack.cancel(optionalExitMessage);
+			continue;
+		}
+		envVars[spec.name] = resultString;
+	}
+	return envVars;
+}
+/** Prompt a user to enable tracing */
+async function selectTracing() {
+	const tracing = await clack.confirm({
+		message: "Add LangSmith tracing?",
+		initialValue: false
+	});
+	if (clack.isCancel(tracing)) {
+		clack.cancel(PROCESSS_EXIT_MESSAGE);
+		process.exit(0);
+	}
+	return tracing;
+}
+/** Prompt a user for their LangSmith API if tracing is enabled */
+async function collectLangSmithKey(tracing, framework) {
+	if (!tracing) return;
+	const exitMessage = `Skipping LangSmith API key. You can add this later in ${framework.envFilePath}`;
+	const result = await clack.password({
+		message: "Enter your LangSmith API key (press enter to skip)?",
+		mask: "*"
+	});
+	const resultString = typeof result === "string" && result.trim() ? result.trim() : void 0;
+	if (clack.isCancel(result) || resultString === void 0) {
+		clack.cancel(exitMessage);
+		return;
+	}
+	return resultString;
+}
+//#endregion
+//#region src/utils/handleError.ts
+function handleError(e) {
+	logger.break();
+	logger.error(`Something went wrong. Please check the error below for more details.`);
+	logger.error(`If the problem persists, please open an issue on GitHub.`);
+	logger.break();
+	if (e && typeof e === "object" && "name" in e && e.name === "ZodError") {
+		const { flatten } = e;
+		for (const [key, value] of Object.entries(flatten().fieldErrors)) logger.error(`- ${key}: ${value}`);
+	} else if (e && typeof e === "object" && "message" in e && typeof e.message === "string") logger.error(e.message);
+}
+//#endregion
+//#region src/utils/fileUtils.ts
+/**
+* Copy a directory recursively. Filters out `node_modules` for dev ergonomics
+*/
+async function copyDir(src, dest) {
+	await fs.promises.cp(src, dest, {
+		recursive: true,
+		filter: (source) => !source.includes("node_modules")
+	});
+}
+/** Loads a json file and asserts type. Performs no checks prior to read. */
+function loadJsonSync(filePath) {
+	const raw = fs.readFileSync(filePath, "utf-8");
+	return JSON.parse(raw);
+}
+/**
+* Write a file, creating parent directories as needed.
+*/
+async function writeFile(filePath, content) {
+	const dir = path.dirname(filePath);
+	await fs.promises.mkdir(dir, { recursive: true });
+	await fs.promises.writeFile(filePath, content);
+}
+//#endregion
+//#region src/utils/git.ts
+/** Initialize a git repo and make an initial commit. Silently ignores failures. */
+function gitInit(dir) {
+	const opts = {
+		cwd: dir,
+		stdio: "ignore"
+	};
+	try {
+		execSync("git init", opts);
+		execSync("git add -A", opts);
+		execSync("git commit -m \"Initial commit\"", opts);
+	} catch {}
+}
+//#endregion
+//#region src/schema/packageJson.ts
+const packageJsonSchema = z.looseObject({
+	name: z.string(),
+	dependencies: z.record(z.string(), z.string()),
+	packageManager: z.string().optional()
+});
+//#endregion
+//#region src/commands/create/transformPackageJson.ts
+/**
+* Pure transformation of a template's package.json for the scaffolded project.
+*/
+function transformPackageJson(packageJson, config) {
+	const result = {
+		...packageJson,
+		dependencies: { ...packageJson.dependencies }
+	};
+	result.name = config.projectName;
+	for (const dep of Object.keys(result.dependencies)) if (config.providerDependencies.includes(dep)) delete result.dependencies[dep];
+	result.dependencies = {
+		...result.dependencies,
+		[config.provider.dependency]: "latest"
+	};
+	delete result.packageManager;
+	return result;
+}
+//#endregion
+//#region src/commands/create/installTemplate.ts
+async function installTemplate(projectPath, framework) {
+	const { address } = framework;
+	switch (address.scheme) {
+		case "github":
+			await downloadGithubTemplate(address, projectPath);
+			break;
+		case "local":
+			await copyDir(address.path, projectPath);
+			break;
+		default: throw new Error(`Invalid address scheme. This should not happen`);
+	}
+}
+/**
+* Download a GitHub template by fetching the repo tarball and extracting it
+* into the project directory.
+*/
+async function downloadGithubTemplate(address, dest) {
+	const tarballUrl = `https://codeload.github.com/${address.owner}/${address.repo}/tar.gz/HEAD`;
+	let tmpDir;
+	try {
+		tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "create-deepagent"));
+		const response = await fetch(tarballUrl);
+		if (!response.ok || !response.body) throw new Error(`Failed to download template from GitHub: ${response.status} ${response.statusText}`);
+		const extractDir = path.join(tmpDir, "extracted");
+		await makeDir(extractDir);
+		await pipeline(Readable.fromWeb(response.body), x({
+			cwd: extractDir,
+			strip: 1
+		}));
+		if (await isDirEmpty(extractDir)) throw new Error(`Downloaded tarball for ${address.owner}/${address.repo} was empty.`);
+		const sourceDir = address.subPath ? path.join(extractDir, address.subPath) : extractDir;
+		if (address.subPath && !await dirExists(sourceDir)) throw new Error(`Subdirectory "${address.subPath}" not found in ${address.owner}/${address.repo}.`);
+		await copyDir(sourceDir, dest);
+	} catch (e) {
+		throw new Error(`Failed to install template from ${address.owner}/${address.repo}: ${e}`, { cause: e });
+	} finally {
+		if (tmpDir) await fs.promises.rm(tmpDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/commands/create/index.ts
+const cliOptionsSchema = z.object({
+	name: z.string().optional(),
+	force: z.boolean().optional()
+});
+const create = new Command().name("create").description("Initialize your project and install dependencies").option("-f, --force", "Force overwrite of existing files").option("-n, --name <name>", "The name for the new project").action(async (opts) => {
+	try {
+		const options = mergeOptions(cliOptionsSchema.parse(opts), await runCreateConfig());
+		await runCreate(await preflightCreate(options), options);
+	} catch (e) {
+		handleError(e);
+		process.exit(1);
+	}
+});
+/**
+* Merges CLI and TUI options. While CLI options are limited, this function will be
+* pretty slim.
+*/
+function mergeOptions(cliOptions, tuiOptions) {
+	const { name, force } = cliOptions;
+	const { frameworkChoice, envVars, langSmithKey, providerChoice, tracing } = tuiOptions;
+	const framework = frameworks[frameworkChoice];
+	return {
+		framework,
+		provider: providers[providerChoice],
+		projectName: name || framework.defaultProjectName,
+		force,
+		tracing,
+		langSmithKey,
+		envVars
+	};
+}
+async function runCreate(projectPath, options) {
+	const s = spinner();
+	try {
+		const { framework, provider, projectName } = options;
+		s.start(`Copying ${framework.title} template...`);
+		await installTemplate(projectPath, framework);
+		const envFile = createEnvFile(framework.envFilePath, options);
+		const allFiles = [...framework.files, envFile];
+		for (const file of allFiles) {
+			const content = file.getContent({ providerConfig: provider });
+			await writeFile(path.join(projectPath, file.path), content);
+		}
+		const packageJsonpath = path.join(projectPath, framework.packageJsonPath);
+		const transformed = transformPackageJson(packageJsonSchema.parse(loadJsonSync(packageJsonpath)), {
+			projectName,
+			provider,
+			providerDependencies: Object.values(providers).map((p) => p.dependency)
+		});
+		fs.writeFileSync(packageJsonpath, JSON.stringify(transformed, null, 2) + "\n");
+		gitInit(projectPath);
+		s.stop();
+		logger.break();
+		logger.success(`${framework.title} project created at ${projectName}`);
+		logger.break();
+		if (framework.postInit) framework.postInit({ projectPath });
+	} finally {
+		s.stop();
+	}
+}
+/**
+* Create an env file with values the user fills in.
+*/
+function createEnvFile(envFilePath, opts) {
+	const envVars = opts.envVars || {};
+	return {
+		path: envFilePath,
+		getContent: () => {
+			const lines = [];
+			for (const [key, value] of Object.entries(envVars)) lines.push(`${key}=${value}`);
+			if (opts.tracing) {
+				lines.push("LANGSMITH_TRACING=true");
+				if (opts.langSmithKey) lines.push(`LANGSMITH_API_KEY=${opts.langSmithKey}`);
+			}
+			return lines.join("\n") + "\n";
+		}
+	};
+}
+//#endregion
+//#region package.json
+var version = "0.1.0";
+//#endregion
+//#region src/index.ts
+async function main() {
+	const program = new Command().name("create-deepagent").description("Scaffold a new Deep Agents project").version(version);
+	program.addCommand(create, { isDefault: true });
+	program.parse();
+}
+main();
+//#endregion
+export {};
+
+//# sourceMappingURL=index.js.map