@voltx/cli 0.1.1 → 0.3.0

package/dist/cli.js

@@ -90,7 +90,7 @@ function printWelcomeBanner(projectName) {
     console.log(`  ${rgb(100, 180, 255, "Next steps:")}`);
     console.log(`  ${rgb(200, 200, 220, `  cd ${projectName}`)}`);
     console.log(`  ${rgb(200, 200, 220, "  pnpm install")}`);
-    console.log(`  ${rgb(200, 200, 220, "  pnpm dev")}`);
+    console.log(`  ${rgb(200, 200, 220, "  pnpm dev          # or: npx voltx dev")}`);
     console.log("");
     console.log(dimRule());
     console.log("");
@@ -146,7 +146,7 @@ __export(create_exports, {
   createProject: () => createProject
 });
 async function createProject(options) {
-  const { name, template = "blank" } = options;
+  const { name, template = "blank", auth = "none" } = options;
   const targetDir = path.resolve(process.cwd(), name);
   if (fs.existsSync(targetDir)) {
     console.error(`[voltx] Directory "${name}" already exists.`);
@@ -154,26 +154,29 @@ async function createProject(options) {
   }
   fs.mkdirSync(targetDir, { recursive: true });
   const templateDeps = {
-    blank: { "@voltx/core": "^0.1.0" },
+    blank: {
+      "@voltx/core": "^0.3.0",
+      "@voltx/server": "^0.3.0"
+    },
     chatbot: {
-      "@voltx/core": "^0.1.0",
-      "@voltx/agents": "^0.1.0",
-      "@voltx/memory": "^0.1.0",
-      "@voltx/ui": "^0.1.0"
+      "@voltx/core": "^0.3.0",
+      "@voltx/ai": "^0.3.0",
+      "@voltx/server": "^0.3.0",
+      "@voltx/memory": "^0.3.0"
     },
     "rag-app": {
-      "@voltx/core": "^0.1.0",
-      "@voltx/rag": "^0.1.0",
-      "@voltx/db": "^0.1.0",
-      "@voltx/ui": "^0.1.0"
+      "@voltx/core": "^0.3.0",
+      "@voltx/ai": "^0.3.0",
+      "@voltx/server": "^0.3.0",
+      "@voltx/rag": "^0.3.0",
+      "@voltx/db": "^0.3.0"
     },
     "agent-app": {
-      "@voltx/core": "^0.1.0",
-      "@voltx/agents": "^0.1.0",
-      "@voltx/memory": "^0.1.0",
-      "@voltx/rag": "^0.1.0",
-      "@voltx/db": "^0.1.0",
-      "@voltx/ui": "^0.1.0"
+      "@voltx/core": "^0.3.0",
+      "@voltx/ai": "^0.3.0",
+      "@voltx/server": "^0.3.0",
+      "@voltx/agents": "^0.3.0",
+      "@voltx/memory": "^0.3.0"
     }
   };
   const packageJson = {
@@ -185,36 +188,335 @@ async function createProject(options) {
       build: "voltx build",
       start: "voltx start"
     },
-    dependencies: templateDeps[template] ?? templateDeps["blank"]
+    dependencies: {
+      ...templateDeps[template] ?? templateDeps["blank"],
+      "@voltx/cli": "^0.3.0",
+      ...auth === "better-auth" ? { "@voltx/auth": "^0.3.0", "better-auth": "^1.5.0" } : {},
+      ...auth === "jwt" ? { "@voltx/auth": "^0.3.0", "jose": "^6.0.0" } : {}
+    },
+    devDependencies: {
+      typescript: "^5.7.0",
+      tsx: "^4.21.0",
+      tsup: "^8.0.0",
+      "@types/node": "^22.0.0"
+    }
   };
   fs.writeFileSync(
     path.join(targetDir, "package.json"),
     JSON.stringify(packageJson, null, 2)
   );
-  const configContent = `import { defineConfig } from "@voltx/core";
+  const hasDb = template === "rag-app" || template === "agent-app" || auth === "better-auth";
+  const provider = template === "rag-app" ? "openai" : "cerebras";
+  const model = template === "rag-app" ? "gpt-4o" : "llama-4-scout-17b-16e";
+  let configContent = `import { defineConfig } from "@voltx/core";
 
 export default defineConfig({
   name: "${name}",
   port: 3000,
   ai: {
-    provider: "openai",
-    model: "gpt-4o",
+    provider: "${provider}",
+    model: "${model}",
+  },`;
+  if (hasDb) {
+    configContent += `
+  db: {
+    url: process.env.DATABASE_URL,
+  },`;
+  }
+  if (auth !== "none") {
+    configContent += `
+  auth: {
+    provider: "${auth}",
+  },`;
+  }
+  configContent += `
+  server: {
+    routesDir: "src/routes",
+    staticDir: "public",
+    cors: true,
   },
 });
 `;
   fs.writeFileSync(path.join(targetDir, "voltx.config.ts"), configContent);
-  fs.mkdirSync(path.join(targetDir, "src", "routes"), { recursive: true });
-  fs.mkdirSync(path.join(targetDir, "src", "agents"), { recursive: true });
-  const indexContent = `import { createApp } from "@voltx/core";
+  fs.mkdirSync(path.join(targetDir, "src", "routes", "api"), { recursive: true });
+  fs.mkdirSync(path.join(targetDir, "public"), { recursive: true });
+  fs.writeFileSync(
+    path.join(targetDir, "src", "index.ts"),
+    `import { createApp } from "@voltx/core";
 import config from "../voltx.config";
 
 const app = createApp(config);
 app.start();
-`;
-  fs.writeFileSync(path.join(targetDir, "src", "index.ts"), indexContent);
+`
+  );
   fs.writeFileSync(
-    path.join(targetDir, ".env.example"),
-    "OPENAI_API_KEY=your-key-here\nDATABASE_URL=\n"
+    path.join(targetDir, "src", "routes", "index.ts"),
+    `// GET / \u2014 Health check
+import type { Context } from "@voltx/server";
+
+export function GET(c: Context) {
+  return c.json({ name: "${name}", status: "ok" });
+}
+`
+  );
+  if (template === "chatbot" || template === "agent-app") {
+    fs.writeFileSync(
+      path.join(targetDir, "src", "routes", "api", "chat.ts"),
+      `// POST /api/chat \u2014 Streaming chat with conversation memory
+import type { Context } from "@voltx/server";
+import { streamText } from "@voltx/ai";
+import { createMemory } from "@voltx/memory";
+
+// In-memory for dev; swap to createMemory("postgres", { url }) for production
+const memory = createMemory({ maxMessages: 50 });
+
+export async function POST(c: Context) {
+  const { messages, conversationId = "default" } = await c.req.json();
+
+  // Store the latest user message
+  const lastMessage = messages[messages.length - 1];
+  if (lastMessage?.role === "user") {
+    await memory.add(conversationId, { role: "user", content: lastMessage.content });
+  }
+
+  // Get conversation history from memory
+  const history = await memory.get(conversationId);
+
+  const result = await streamText({
+    model: "${provider}:${model}",
+    system: "You are a helpful AI assistant.",
+    messages: history.map((m) => ({ role: m.role, content: m.content })),
+  });
+
+  // Store assistant response after stream completes
+  result.text.then(async (text) => {
+    await memory.add(conversationId, { role: "assistant", content: text });
+  });
+
+  return result.toSSEResponse();
+}
+`
+    );
+  }
+  if (template === "agent-app") {
+    fs.mkdirSync(path.join(targetDir, "src", "agents"), { recursive: true });
+    fs.mkdirSync(path.join(targetDir, "src", "tools"), { recursive: true });
+    fs.writeFileSync(
+      path.join(targetDir, "src", "agents", "assistant.ts"),
+      `import { createAgent } from "@voltx/agents";
+import { searchTool } from "../tools/search";
+
+export const assistant = createAgent({
+  name: "assistant",
+  model: "${provider}:${model}",
+  instructions: "You are a helpful AI assistant. Use your tools when needed.",
+  tools: [searchTool],
+  maxIterations: 5,
+});
+`
+    );
+    fs.writeFileSync(
+      path.join(targetDir, "src", "tools", "search.ts"),
+      `import type { Tool } from "@voltx/agents";
+
+export const searchTool: Tool = {
+  name: "search",
+  description: "Search for information on a topic.",
+  parameters: {
+    type: "object",
+    properties: { query: { type: "string", description: "The search query" } },
+    required: ["query"],
+  },
+  async execute(args: { query: string }) {
+    return \`Search results for "\${args.query}": Placeholder \u2014 connect a real search API.\`;
+  },
+};
+`
+    );
+    fs.writeFileSync(
+      path.join(targetDir, "src", "routes", "api", "agent.ts"),
+      `import type { Context } from "@voltx/server";
+import { assistant } from "../../agents/assistant";
+
+export async function POST(c: Context) {
+  const { input } = await c.req.json();
+  if (!input) return c.json({ error: "Missing 'input' field" }, 400);
+  const result = await assistant.run(input);
+  return c.json({ content: result.content, steps: result.steps });
+}
+`
+    );
+  }
+  if (template === "rag-app") {
+    const embedModel = "openai:text-embedding-3-small";
+    fs.mkdirSync(path.join(targetDir, "src", "routes", "api", "rag"), { recursive: true });
+    fs.writeFileSync(
+      path.join(targetDir, "src", "routes", "api", "rag", "query.ts"),
+      `// POST /api/rag/query \u2014 Query documents with RAG
+import type { Context } from "@voltx/server";
+import { streamText } from "@voltx/ai";
+import { createRAGPipeline, createEmbedder } from "@voltx/rag";
+import { createVectorStore } from "@voltx/db";
+
+const vectorStore = createVectorStore(); // swap to "pinecone" or "pgvector" for production
+const embedder = createEmbedder({ model: "${embedModel}" });
+const rag = createRAGPipeline({ embedder, vectorStore });
+
+export async function POST(c: Context) {
+  const { question } = await c.req.json();
+
+  const context = await rag.getContext(question, { topK: 5 });
+
+  const result = await streamText({
+    model: "${provider}:${model}",
+    system: \`Answer the user's question based on the following context. If the context doesn't contain relevant information, say so.\\n\\nContext:\\n\${context}\`,
+    messages: [{ role: "user", content: question }],
+  });
+
+  return result.toSSEResponse();
+}
+`
+    );
+    fs.writeFileSync(
+      path.join(targetDir, "src", "routes", "api", "rag", "ingest.ts"),
+      `// POST /api/rag/ingest \u2014 Ingest documents into the vector store
+import type { Context } from "@voltx/server";
+import { createRAGPipeline, createEmbedder } from "@voltx/rag";
+import { createVectorStore } from "@voltx/db";
+
+const vectorStore = createVectorStore();
+const embedder = createEmbedder({ model: "${embedModel}" });
+const rag = createRAGPipeline({ embedder, vectorStore });
+
+export async function POST(c: Context) {
+  const { text, idPrefix } = await c.req.json();
+
+  if (!text || typeof text !== "string") {
+    return c.json({ error: "Missing 'text' field" }, 400);
+  }
+
+  const result = await rag.ingest(text, idPrefix ?? "doc");
+  return c.json({ status: "ok", chunks: result.chunks, ids: result.ids });
+}
+`
+    );
+  }
+  if (auth === "better-auth") {
+    fs.mkdirSync(path.join(targetDir, "src", "routes", "api", "auth"), { recursive: true });
+    fs.writeFileSync(
+      path.join(targetDir, "src", "routes", "api", "auth", "[...path].ts"),
+      `// ALL /api/auth/* \u2014 Better Auth handler
+import type { Context } from "@voltx/server";
+import { auth } from "../../../lib/auth";
+import { createAuthHandler } from "@voltx/auth";
+
+const handler = createAuthHandler(auth);
+
+export const GET = (c: Context) => handler(c);
+export const POST = (c: Context) => handler(c);
+`
+    );
+    fs.mkdirSync(path.join(targetDir, "src", "lib"), { recursive: true });
+    fs.writeFileSync(
+      path.join(targetDir, "src", "lib", "auth.ts"),
+      `// Auth configuration \u2014 Better Auth with DB-backed sessions
+import { createAuth, createAuthMiddleware } from "@voltx/auth";
+
+export const auth = createAuth("better-auth", {
+  database: process.env.DATABASE_URL!,
+  emailAndPassword: true,
+});
+
+export const authMiddleware = createAuthMiddleware({
+  provider: auth,
+  publicPaths: ["/api/auth", "/api/health", "/"],
+});
+`
+    );
+  } else if (auth === "jwt") {
+    fs.mkdirSync(path.join(targetDir, "src", "lib"), { recursive: true });
+    fs.writeFileSync(
+      path.join(targetDir, "src", "lib", "auth.ts"),
+      `// Auth configuration \u2014 JWT (stateless)
+import { createAuth, createAuthMiddleware } from "@voltx/auth";
+
+export const jwt = createAuth("jwt", {
+  secret: process.env.JWT_SECRET!,
+  expiresIn: "7d",
+});
+
+export const authMiddleware = createAuthMiddleware({
+  provider: jwt,
+  publicPaths: ["/api/auth", "/api/health", "/"],
+});
+`
+    );
+    fs.writeFileSync(
+      path.join(targetDir, "src", "routes", "api", "auth.ts"),
+      `// POST /api/auth/login \u2014 Example JWT login route
+import type { Context } from "@voltx/server";
+import { jwt } from "../../lib/auth";
+
+export async function POST(c: Context) {
+  const { email, password } = await c.req.json();
+
+  if (!email || !password) {
+    return c.json({ error: "Email and password are required" }, 400);
+  }
+
+  const token = await jwt.sign({ sub: email, email });
+  return c.json({ token });
+}
+`
+    );
+  }
+  let envContent = "";
+  if (template === "rag-app") {
+    envContent += "# \u2500\u2500\u2500 LLM Provider \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nOPENAI_API_KEY=sk-...\n\n";
+    envContent += "# \u2500\u2500\u2500 Database (Neon Postgres) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nDATABASE_URL=postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/dbname?sslmode=require\n\n";
+    envContent += "# \u2500\u2500\u2500 Vector Database (Pinecone) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nPINECONE_API_KEY=pc-...\nPINECONE_INDEX=voltx-embeddings\n\n";
+  } else if (template === "chatbot" || template === "agent-app") {
+    envContent += "# \u2500\u2500\u2500 LLM Provider \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nCEREBRAS_API_KEY=csk-...\n\n";
+    if (template === "agent-app") {
+      envContent += "# \u2500\u2500\u2500 Database (Neon Postgres \u2014 optional) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nDATABASE_URL=\n\n";
+    }
+  } else {
+    envContent += "# \u2500\u2500\u2500 LLM Provider (add your key) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n# OPENAI_API_KEY=sk-...\n# CEREBRAS_API_KEY=csk-...\n\n";
+  }
+  if (auth === "better-auth") {
+    envContent += "# \u2500\u2500\u2500 Auth (Better Auth) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nBETTER_AUTH_SECRET=your-secret-key-min-32-chars-here\nBETTER_AUTH_URL=http://localhost:3000\n";
+    if (template !== "rag-app" && template !== "agent-app") {
+      envContent += "DATABASE_URL=postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/dbname?sslmode=require\n";
+    }
+    envContent += "# GITHUB_CLIENT_ID=\n# GITHUB_CLIENT_SECRET=\n\n";
+  } else if (auth === "jwt") {
+    envContent += "# \u2500\u2500\u2500 Auth (JWT) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nJWT_SECRET=your-jwt-secret-key\n\n";
+  }
+  envContent += "# \u2500\u2500\u2500 App \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nPORT=3000\nNODE_ENV=development\n";
+  fs.writeFileSync(path.join(targetDir, ".env.example"), envContent);
+  fs.writeFileSync(
+    path.join(targetDir, ".gitignore"),
+    "node_modules\ndist\n.env\n"
+  );
+  fs.writeFileSync(
+    path.join(targetDir, "tsconfig.json"),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          target: "ES2022",
+          module: "ESNext",
+          moduleResolution: "bundler",
+          strict: true,
+          esModuleInterop: true,
+          skipLibCheck: true,
+          outDir: "dist",
+          rootDir: "src"
+        },
+        include: ["src"]
+      },
+      null,
+      2
+    )
   );
   printWelcomeBanner(name);
 }
@@ -229,12 +531,14 @@ var init_create = __esm({
     if (isDirectRun) {
       const projectName = process.argv[2];
       if (!projectName) {
-        console.log("Usage: create-voltx-app <project-name> [--template chatbot]");
+        console.log("Usage: create-voltx-app <project-name> [--template chatbot] [--auth jwt]");
         process.exit(1);
       }
       const templateFlag = process.argv.indexOf("--template");
       const template = templateFlag !== -1 ? process.argv[templateFlag + 1] : "blank";
-      createProject({ name: projectName, template }).catch((err) => {
+      const authFlag = process.argv.indexOf("--auth");
+      const auth = authFlag !== -1 ? process.argv[authFlag + 1] : "none";
+      createProject({ name: projectName, template, auth }).catch((err) => {
         console.error("[voltx] Error:", err);
         process.exit(1);
       });
@@ -242,56 +546,670 @@ var init_create = __esm({
   }
 });
 
+// src/dev.ts
+var dev_exports = {};
+__export(dev_exports, {
+  runDev: () => runDev
+});
+async function runDev(options = {}) {
+  const cwd = process.cwd();
+  const {
+    port,
+    entry = findEntryPoint(cwd),
+    clearScreen = true
+  } = options;
+  if (!entry) {
+    console.error("[voltx] Could not find entry point. Expected src/index.ts or src/index.js");
+    process.exit(1);
+  }
+  const entryPath = (0, import_node_path.resolve)(cwd, entry);
+  if (!(0, import_node_fs.existsSync)(entryPath)) {
+    console.error(`[voltx] Entry file not found: ${entry}`);
+    process.exit(1);
+  }
+  const envFile = (0, import_node_path.resolve)(cwd, ".env");
+  const env = {
+    ...process.env,
+    NODE_ENV: "development"
+  };
+  if (port) {
+    env.PORT = String(port);
+  }
+  printDevBanner(entry, port);
+  const tsxArgs = ["watch"];
+  if (clearScreen) {
+    tsxArgs.push("--clear-screen=false");
+  }
+  const watchDirs = [
+    "src/routes",
+    "src/agents",
+    "src/tools",
+    "src/jobs",
+    "src/lib",
+    "voltx.config.ts",
+    ...options.watch ?? []
+  ];
+  tsxArgs.push("--ignore=node_modules", "--ignore=dist", "--ignore=.turbo");
+  tsxArgs.push(entry);
+  const tsxBin = findTsxBin(cwd);
+  let child;
+  if (tsxBin) {
+    child = (0, import_node_child_process.spawn)(tsxBin, tsxArgs, {
+      cwd,
+      env,
+      stdio: "inherit"
+    });
+  } else {
+    child = (0, import_node_child_process.spawn)("npx", ["tsx", ...tsxArgs], {
+      cwd,
+      env,
+      stdio: "inherit"
+    });
+  }
+  const signals = ["SIGINT", "SIGTERM"];
+  for (const signal of signals) {
+    process.on(signal, () => {
+      child.kill(signal);
+    });
+  }
+  child.on("error", (err) => {
+    if (err.code === "ENOENT") {
+      console.error("[voltx] tsx not found. Install it with: npm install -D tsx");
+      console.error("[voltx] Or run your app directly: npx tsx watch src/index.ts");
+    } else {
+      console.error("[voltx] Dev server error:", err.message);
+    }
+    process.exit(1);
+  });
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+}
+function findEntryPoint(cwd) {
+  const candidates = [
+    "src/index.ts",
+    "src/index.js",
+    "src/index.mts",
+    "src/main.ts",
+    "src/main.js",
+    "index.ts",
+    "index.js"
+  ];
+  for (const candidate of candidates) {
+    if ((0, import_node_fs.existsSync)((0, import_node_path.join)(cwd, candidate))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function findTsxBin(cwd) {
+  const localBin = (0, import_node_path.join)(cwd, "node_modules", ".bin", "tsx");
+  if ((0, import_node_fs.existsSync)(localBin)) return localBin;
+  const parentBin = (0, import_node_path.join)(cwd, "..", "node_modules", ".bin", "tsx");
+  if ((0, import_node_fs.existsSync)(parentBin)) return parentBin;
+  const rootBin = (0, import_node_path.join)(cwd, "..", "..", "node_modules", ".bin", "tsx");
+  if ((0, import_node_fs.existsSync)(rootBin)) return rootBin;
+  return null;
+}
+function printDevBanner(entry, port) {
+  console.log("");
+  console.log("  \u26A1 VoltX Dev Server");
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log(`  Entry:   ${entry}`);
+  if (port) {
+    console.log(`  Port:    ${port}`);
+  }
+  console.log(`  Mode:    development (hot reload)`);
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log("");
+}
+var import_node_child_process, import_node_path, import_node_fs;
+var init_dev = __esm({
+  "src/dev.ts"() {
+    "use strict";
+    import_node_child_process = require("child_process");
+    import_node_path = require("path");
+    import_node_fs = require("fs");
+  }
+});
+
+// src/build.ts
+var build_exports = {};
+__export(build_exports, {
+  runBuild: () => runBuild
+});
+async function runBuild(options = {}) {
+  const cwd = process.cwd();
+  const {
+    entry = findEntryPoint2(cwd),
+    outDir = "dist",
+    minify = true,
+    sourcemap = false
+  } = options;
+  if (!entry) {
+    console.error("[voltx] Could not find entry point. Expected src/index.ts");
+    process.exit(1);
+  }
+  const entryPath = (0, import_node_path2.resolve)(cwd, entry);
+  if (!(0, import_node_fs2.existsSync)(entryPath)) {
+    console.error(`[voltx] Entry file not found: ${entry}`);
+    process.exit(1);
+  }
+  console.log("");
+  console.log("  \u26A1 VoltX Build");
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log(`  Entry:   ${entry}`);
+  console.log(`  Output:  ${outDir}/`);
+  console.log(`  Minify:  ${minify}`);
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log("");
+  (0, import_node_fs2.mkdirSync)((0, import_node_path2.resolve)(cwd, outDir), { recursive: true });
+  console.log("  [1/2] Building server...");
+  const tsupArgs = [
+    entry,
+    "--format",
+    "esm",
+    "--out-dir",
+    outDir,
+    "--clean",
+    "--target",
+    "node20"
+  ];
+  if (minify) tsupArgs.push("--minify");
+  if (sourcemap) tsupArgs.push("--sourcemap");
+  tsupArgs.push("--no-splitting");
+  const tsupBin = findBin(cwd, "tsup");
+  await runCommand(
+    tsupBin ?? "npx",
+    tsupBin ? tsupArgs : ["tsup", ...tsupArgs],
+    cwd
+  );
+  console.log("  \u2713 Server built successfully");
+  const frontendDir = (0, import_node_path2.resolve)(cwd, "src", "frontend");
+  const viteConfig = (0, import_node_path2.resolve)(cwd, "vite.config.ts");
+  const hasFrontend = (0, import_node_fs2.existsSync)(frontendDir) || (0, import_node_fs2.existsSync)(viteConfig);
+  if (hasFrontend) {
+    console.log("  [2/2] Building frontend...");
+    const viteBin = findBin(cwd, "vite");
+    const viteArgs = ["build", "--outDir", (0, import_node_path2.join)(outDir, "public")];
+    await runCommand(
+      viteBin ?? "npx",
+      viteBin ? viteArgs : ["vite", ...viteArgs],
+      cwd
+    );
+    console.log("  \u2713 Frontend built successfully");
+  } else {
+    console.log("  [2/2] No frontend found, skipping...");
+  }
+  console.log("");
+  console.log("  \u26A1 Build complete!");
+  console.log(`  Run \`voltx start\` to start the production server.`);
+  console.log("");
+}
+function findEntryPoint2(cwd) {
+  const candidates = [
+    "src/index.ts",
+    "src/index.js",
+    "src/index.mts",
+    "src/main.ts",
+    "src/main.js"
+  ];
+  for (const candidate of candidates) {
+    if ((0, import_node_fs2.existsSync)((0, import_node_path2.join)(cwd, candidate))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function findBin(cwd, name) {
+  const paths = [
+    (0, import_node_path2.join)(cwd, "node_modules", ".bin", name),
+    (0, import_node_path2.join)(cwd, "..", "node_modules", ".bin", name),
+    (0, import_node_path2.join)(cwd, "..", "..", "node_modules", ".bin", name)
+  ];
+  for (const p of paths) {
+    if ((0, import_node_fs2.existsSync)(p)) return p;
+  }
+  return null;
+}
+function runCommand(cmd, args2, cwd) {
+  return new Promise((resolve6, reject) => {
+    const child = (0, import_node_child_process2.spawn)(cmd, args2, {
+      cwd,
+      stdio: "inherit",
+      env: { ...process.env, NODE_ENV: "production" }
+    });
+    child.on("error", (err) => {
+      if (err.code === "ENOENT") {
+        console.error(`[voltx] ${cmd} not found. Install it with: npm install -D ${cmd}`);
+      }
+      reject(err);
+    });
+    child.on("exit", (code) => {
+      if (code === 0) resolve6();
+      else reject(new Error(`${cmd} exited with code ${code}`));
+    });
+  });
+}
+var import_node_child_process2, import_node_path2, import_node_fs2;
+var init_build = __esm({
+  "src/build.ts"() {
+    "use strict";
+    import_node_child_process2 = require("child_process");
+    import_node_path2 = require("path");
+    import_node_fs2 = require("fs");
+  }
+});
+
+// src/start.ts
+var start_exports = {};
+__export(start_exports, {
+  runStart: () => runStart
+});
+async function runStart(options = {}) {
+  const cwd = process.cwd();
+  const { port, outDir = "dist" } = options;
+  const distDir = (0, import_node_path3.resolve)(cwd, outDir);
+  if (!(0, import_node_fs3.existsSync)(distDir)) {
+    console.error(`[voltx] Build output not found at ${outDir}/`);
+    console.error("[voltx] Run `voltx build` first to create a production build.");
+    process.exit(1);
+  }
+  const entry = options.entry ?? findDistEntry(distDir);
+  if (!entry) {
+    console.error(`[voltx] No entry file found in ${outDir}/`);
+    console.error("[voltx] Expected index.js, index.mjs, or main.js");
+    process.exit(1);
+  }
+  const entryPath = (0, import_node_path3.resolve)(distDir, entry);
+  if (!(0, import_node_fs3.existsSync)(entryPath)) {
+    console.error(`[voltx] Entry file not found: ${outDir}/${entry}`);
+    process.exit(1);
+  }
+  const env = {
+    ...process.env,
+    NODE_ENV: "production"
+  };
+  if (port) {
+    env.PORT = String(port);
+  }
+  console.log("");
+  console.log("  \u26A1 VoltX Production Server");
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log(`  Entry:   ${outDir}/${entry}`);
+  if (port) {
+    console.log(`  Port:    ${port}`);
+  }
+  console.log(`  Mode:    production`);
+  console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+  console.log("");
+  const child = (0, import_node_child_process3.spawn)("node", [entryPath], {
+    cwd,
+    env,
+    stdio: "inherit"
+  });
+  const signals = ["SIGINT", "SIGTERM"];
+  for (const signal of signals) {
+    process.on(signal, () => {
+      child.kill(signal);
+    });
+  }
+  child.on("error", (err) => {
+    console.error("[voltx] Failed to start production server:", err.message);
+    process.exit(1);
+  });
+  child.on("exit", (code) => {
+    process.exit(code ?? 0);
+  });
+}
+function findDistEntry(distDir) {
+  const candidates = [
+    "index.mjs",
+    "index.js",
+    "index.cjs",
+    "main.mjs",
+    "main.js",
+    "src/index.mjs",
+    "src/index.js"
+  ];
+  for (const candidate of candidates) {
+    if ((0, import_node_fs3.existsSync)((0, import_node_path3.join)(distDir, candidate))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+var import_node_child_process3, import_node_path3, import_node_fs3;
+var init_start = __esm({
+  "src/start.ts"() {
+    "use strict";
+    import_node_child_process3 = require("child_process");
+    import_node_path3 = require("path");
+    import_node_fs3 = require("fs");
+  }
+});
+
+// src/generate.ts
+var generate_exports = {};
+__export(generate_exports, {
+  runGenerate: () => runGenerate
+});
+async function runGenerate(options) {
+  const cwd = process.cwd();
+  const { type, name } = options;
+  switch (type) {
+    case "route":
+      generateRoute(cwd, name, options.method);
+      break;
+    case "agent":
+      generateAgent(cwd, name);
+      break;
+    case "tool":
+      generateTool(cwd, name);
+      break;
+    case "job":
+      generateJob(cwd, name);
+      break;
+    default:
+      console.error(`[voltx] Unknown generator type: ${type}`);
+      console.error("[voltx] Available: route, agent, tool, job");
+      process.exit(1);
+  }
+}
+function generateRoute(cwd, name, method = "POST") {
+  const routePath = name.startsWith("/") ? name.slice(1) : name;
+  const filePath = (0, import_node_path4.join)(cwd, "src", "routes", `${routePath}.ts`);
+  if ((0, import_node_fs4.existsSync)(filePath)) {
+    console.error(`[voltx] Route already exists: src/routes/${routePath}.ts`);
+    process.exit(1);
+  }
+  const upperMethod = method.toUpperCase();
+  const urlPath = "/" + routePath;
+  const content = `// ${upperMethod} ${urlPath}
+import type { Context } from "@voltx/server";
+
+export async function ${upperMethod}(c: Context) {
+  return c.json({ message: "Hello from ${urlPath}" });
+}
+`;
+  writeFileSafe(filePath, content);
+  console.log(`  \u2713 Created route: src/routes/${routePath}.ts`);
+  console.log(`    ${upperMethod} ${urlPath}`);
+}
+function generateAgent(cwd, name) {
+  const filePath = (0, import_node_path4.join)(cwd, "src", "agents", `${name}.ts`);
+  if ((0, import_node_fs4.existsSync)(filePath)) {
+    console.error(`[voltx] Agent already exists: src/agents/${name}.ts`);
+    process.exit(1);
+  }
+  const content = `// Agent: ${name}
+import { createAgent } from "@voltx/agents";
+
+export const ${toCamelCase(name)} = createAgent({
+  name: "${name}",
+  model: "cerebras:llama-4-scout-17b-16e",
+  instructions: "You are a helpful AI assistant named ${name}.",
+  tools: [
+    // Add tools here:
+    // {
+    //   name: "example",
+    //   description: "An example tool",
+    //   parameters: { type: "object", properties: { input: { type: "string" } }, required: ["input"] },
+    //   execute: async (params) => \`Processed: \${params.input}\`,
+    // },
+  ],
+});
+`;
+  writeFileSafe(filePath, content);
+  console.log(`  \u2713 Created agent: src/agents/${name}.ts`);
+}
+function generateTool(cwd, name) {
+  const filePath = (0, import_node_path4.join)(cwd, "src", "tools", `${name}.ts`);
+  if ((0, import_node_fs4.existsSync)(filePath)) {
+    console.error(`[voltx] Tool already exists: src/tools/${name}.ts`);
+    process.exit(1);
+  }
+  const content = `// Tool: ${name}
+
+export const ${toCamelCase(name)}Tool = {
+  name: "${name}",
+  description: "TODO: Describe what this tool does",
+  parameters: {
+    type: "object" as const,
+    properties: {
+      input: { type: "string", description: "The input to process" },
+    },
+    required: ["input"],
+  },
+  execute: async (params: { input: string }): Promise<string> => {
+    // TODO: Implement tool logic
+    return \`${name} result for: \${params.input}\`;
+  },
+};
+`;
+  writeFileSafe(filePath, content);
+  console.log(`  \u2713 Created tool: src/tools/${name}.ts`);
+}
+function generateJob(cwd, name) {
+  const filePath = (0, import_node_path4.join)(cwd, "src", "jobs", `${name}.ts`);
+  if ((0, import_node_fs4.existsSync)(filePath)) {
+    console.error(`[voltx] Job already exists: src/jobs/${name}.ts`);
+    process.exit(1);
+  }
+  const content = `// Job: ${name}
+// Runs on a schedule or triggered via ctx.jobs.enqueue("${name}", data)
+
+export const config = {
+  // Cron schedule (uncomment to enable):
+  // schedule: "0 */6 * * *",  // every 6 hours
+  //
+  // Or make it a queue job (triggered on-demand):
+  queue: true,
+  retries: 3,
+  timeout: "5m",
+};
+
+export async function run(ctx: any, data?: Record<string, unknown>) {
+  console.log("[job:${name}] Running...", data);
+
+  // TODO: Implement job logic
+
+  console.log("[job:${name}] Done.");
+}
+`;
+  writeFileSafe(filePath, content);
+  console.log(`  \u2713 Created job: src/jobs/${name}.ts`);
+}
+function writeFileSafe(filePath, content) {
+  const dir = (0, import_node_path4.dirname)(filePath);
+  (0, import_node_fs4.mkdirSync)(dir, { recursive: true });
+  (0, import_node_fs4.writeFileSync)(filePath, content, "utf-8");
+}
+function toCamelCase(str) {
+  return str.replace(/[-_](.)/g, (_, c) => c.toUpperCase()).replace(/^(.)/, (_, c) => c.toLowerCase());
+}
+var import_node_fs4, import_node_path4;
+var init_generate = __esm({
+  "src/generate.ts"() {
+    "use strict";
+    import_node_fs4 = require("fs");
+    import_node_path4 = require("path");
+  }
+});
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CLI_VERSION: () => CLI_VERSION,
+  createProject: () => createProject,
+  runBuild: () => runBuild,
+  runDev: () => runDev,
+  runGenerate: () => runGenerate,
+  runStart: () => runStart
+});
+var CLI_VERSION;
+var init_index = __esm({
+  "src/index.ts"() {
+    "use strict";
+    init_create();
+    init_dev();
+    init_build();
+    init_start();
+    init_generate();
+    CLI_VERSION = "0.2.0";
+  }
+});
+
 // src/cli.ts
 var args = process.argv.slice(2);
 var command = args[0];
+function parseFlag(flag) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && args[idx + 1] ? args[idx + 1] : void 0;
+}
+function hasFlag(flag) {
+  return args.includes(flag);
+}
+function parsePort() {
+  const portStr = parseFlag("--port") ?? parseFlag("-p");
+  return portStr ? Number(portStr) : void 0;
+}
 async function main() {
   switch (command) {
+    // ─── voltx create ──────────────────────────────────────────────────
     case "create": {
       const projectName = args[1];
-      if (!projectName) {
-        console.error("[voltx] Usage: voltx create <project-name> [--template chatbot|rag-app|agent-app]");
+      if (!projectName || projectName.startsWith("-")) {
+        console.error("[voltx] Usage: voltx create <project-name> [--template chatbot|rag-app|agent-app] [--auth better-auth|jwt|none]");
         process.exit(1);
       }
-      const templateFlag = args.indexOf("--template");
-      const template = templateFlag !== -1 ? args[templateFlag + 1] : "blank";
+      const template = parseFlag("--template");
+      const auth = parseFlag("--auth");
       const { createProject: createProject2 } = await Promise.resolve().then(() => (init_create(), create_exports));
-      await createProject2({ name: projectName, template });
+      await createProject2({ name: projectName, template: template ?? "blank", auth: auth ?? "none" });
       break;
     }
+    // ─── voltx dev ─────────────────────────────────────────────────────
     case "dev": {
-      console.log("[voltx] Starting dev server...");
-      console.log("[voltx] Dev server not yet implemented \u2014 coming in Phase 2");
+      const { runDev: runDev2 } = await Promise.resolve().then(() => (init_dev(), dev_exports));
+      await runDev2({
+        port: parsePort(),
+        entry: parseFlag("--entry"),
+        clearScreen: !hasFlag("--no-clear")
+      });
       break;
     }
+    // ─── voltx build ───────────────────────────────────────────────────
     case "build": {
-      console.log("[voltx] Building for production...");
-      console.log("[voltx] Build not yet implemented \u2014 coming in Phase 2");
+      const { runBuild: runBuild2 } = await Promise.resolve().then(() => (init_build(), build_exports));
+      await runBuild2({
+        entry: parseFlag("--entry"),
+        outDir: parseFlag("--out-dir") ?? parseFlag("-o"),
+        minify: !hasFlag("--no-minify"),
+        sourcemap: hasFlag("--sourcemap")
+      });
       break;
     }
+    // ─── voltx start ──────────────────────────────────────────────────
     case "start": {
-      console.log("[voltx] Starting production server...");
-      console.log("[voltx] Start not yet implemented \u2014 coming in Phase 2");
+      const { runStart: runStart2 } = await Promise.resolve().then(() => (init_start(), start_exports));
+      await runStart2({
+        port: parsePort(),
+        outDir: parseFlag("--out-dir") ?? parseFlag("-o"),
+        entry: parseFlag("--entry")
+      });
       break;
     }
+    // ─── voltx generate ───────────────────────────────────────────────
+    case "generate":
+    case "g": {
+      const type = args[1];
+      const name = args[2];
+      if (!type || !name) {
+        console.error("[voltx] Usage: voltx generate <type> <name>");
+        console.error("");
+        console.error("  Types:");
+        console.error("    route <path>    Generate a new API route     (e.g., api/users)");
+        console.error("    agent <name>    Generate a new agent         (e.g., assistant)");
+        console.error("    tool  <name>    Generate a new tool          (e.g., search)");
+        console.error("    job   <name>    Generate a new background job (e.g., cleanup)");
+        console.error("");
+        console.error("  Options:");
+        console.error("    --method <GET|POST|PUT|DELETE>   HTTP method for routes (default: POST)");
+        process.exit(1);
+      }
+      const { runGenerate: runGenerate2 } = await Promise.resolve().then(() => (init_generate(), generate_exports));
+      await runGenerate2({
+        type,
+        name,
+        method: parseFlag("--method")
+      });
+      break;
+    }
+    // ─── voltx --version ──────────────────────────────────────────────
+    case "--version":
+    case "-v": {
+      const { CLI_VERSION: CLI_VERSION2 } = await Promise.resolve().then(() => (init_index(), index_exports));
+      console.log(`voltx v${CLI_VERSION2}`);
+      break;
+    }
+    // ─── voltx help / default ─────────────────────────────────────────
+    case "help":
+    case "--help":
+    case "-h":
     default: {
-      console.log(`
+      printHelp();
+    }
+  }
+}
+function printHelp() {
+  console.log(`
   \u26A1 voltx \u2014 The AI-first full-stack framework
 
   Usage:
-    voltx create <name>  Create a new VoltX project
-    voltx dev            Start the development server
-    voltx build          Build for production
-    voltx start          Start the production server
+    voltx <command> [options]
 
-  Options:
-    --template <type>    Template: chatbot, rag-app, agent-app, blank (default)
+  Commands:
+    create <name>              Create a new VoltX project
+    dev                        Start the development server (hot reload)
+    build                      Build for production
+    start                      Start the production server
+    generate <type> <name>     Generate routes, agents, tools, or jobs
 
-  Example:
-    voltx create my-app --template chatbot
-      `);
-    }
-  }
+  Create Options:
+    --template <type>          Template: chatbot, rag-app, agent-app, blank (default)
+    --auth <provider>          Auth: better-auth, jwt, none (default)
+
+  Dev Options:
+    --port, -p <number>        Port override
+    --entry <file>             Custom entry file (default: src/index.ts)
+    --no-clear                 Don't clear screen on restart
+
+  Build Options:
+    --entry <file>             Custom entry file
+    --out-dir, -o <dir>        Output directory (default: dist)
+    --no-minify                Skip minification
+    --sourcemap                Generate source maps
+
+  Start Options:
+    --port, -p <number>        Port override
+    --out-dir, -o <dir>        Build output directory (default: dist)
+    --entry <file>             Entry file within output dir
+
+  Generate Types:
+    route <path>               API route      (e.g., voltx generate route api/users)
+    agent <name>               Agent          (e.g., voltx generate agent assistant)
+    tool  <name>               Tool           (e.g., voltx generate tool search)
+    job   <name>               Background job (e.g., voltx generate job cleanup)
+
+  Examples:
+    voltx create my-app --template chatbot --auth jwt
+    voltx dev --port 4000
+    voltx build --sourcemap
+    voltx start
+    voltx generate route api/users --method GET
+    voltx generate agent assistant
+  `);
 }
 main().catch((err) => {
   console.error("[voltx] Fatal error:", err);