awel 0.1.1 → 0.2.0

package/dist/cli/server.d.ts

@@ -2,6 +2,7 @@ interface ServerOptions {
     awelPort: number;
     targetPort: number;
     projectCwd: string;
+    fresh?: boolean;
 }
-export declare function startServer({ awelPort, targetPort, projectCwd }: ServerOptions): Promise<void>;
+export declare function startServer({ awelPort, targetPort, projectCwd, fresh }: ServerOptions): Promise<void>;
 export {};

package/dist/cli/server.js

@@ -8,6 +8,7 @@ import { createInspectorRoute } from './inspector.js';
 import { createCommentPopupRoute } from './comment-popup.js';
 import { trackProxySocket } from './devserver.js';
 import { getMimeType } from './config.js';
+import { markProjectReady } from './awel-config.js';
 import { awel } from './logger.js';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -37,8 +38,9 @@ function serveDashboardIndex() {
         return null;
     return readFileSync(indexPath, 'utf-8');
 }
-export async function startServer({ awelPort, targetPort, projectCwd }) {
+export async function startServer({ awelPort, targetPort, projectCwd, fresh }) {
     const app = new Hono();
+    let isFresh = fresh ?? false;
     // Create a proxy for WebSocket connections
     const wsProxy = httpProxy.createProxyServer({
         target: `http://localhost:${targetPort}`,
@@ -52,13 +54,22 @@ export async function startServer({ awelPort, targetPort, projectCwd }) {
         trackProxySocket(proxySocket);
     });
     // Mount agent API routes
-    app.route('/', createAgentRoute(projectCwd, targetPort));
+    app.route('/', createAgentRoute(projectCwd, targetPort, () => isFresh));
     // Mount undo API routes
     app.route('/', createUndoRoute(projectCwd));
     // Mount inspector relay routes
     app.route('/', createInspectorRoute(projectCwd));
     // Serve the comment popup page (loaded in an iframe by the host script)
     app.route('/', createCommentPopupRoute());
+    // ─── Project Status Endpoints ─────────────────────────────
+    app.get('/api/project/status', (c) => {
+        return c.json({ fresh: isFresh });
+    });
+    app.post('/api/project/mark-ready', (c) => {
+        markProjectReady(projectCwd);
+        isFresh = false;
+        return c.json({ success: true });
+    });
     // Serve the host script
     app.get('/_awel/host.js', async (c) => {
         const hostDistPath = join(__dirname, '../host/host.js');
@@ -89,7 +100,7 @@ export async function startServer({ awelPort, targetPort, projectCwd }) {
         return c.text('Not found', 404);
     });
     // Proxy all other requests to the target app
-    app.all('*', createProxyMiddleware(targetPort, projectCwd));
+    app.all('*', createProxyMiddleware(targetPort, projectCwd, () => isFresh));
     // Create the HTTP server with Hono
     const server = serve({
         fetch: app.fetch,

package/dist/cli/templates/blank/AGENT.md

@@ -0,0 +1,24 @@
+# Project Guide
+
+## Overview
+
+This is a blank Next.js project created with Awel. It uses the App Router, TypeScript, and Tailwind CSS.
+
+## Structure
+
+- `src/app/page.tsx` — Home page
+- `src/app/layout.tsx` — Root layout with metadata and fonts
+- `src/app/globals.css` — Global styles and Tailwind imports
+
+## Conventions
+
+- Use server components by default; add `'use client'` only when needed
+- Style with Tailwind CSS utility classes
+- Keep components in `src/components/`
+- Use TypeScript for all files
+
+## Example Prompts
+
+- "Add a navigation bar with links to Home and About pages"
+- "Create an About page at /about with a brief bio section"
+- "Add a dark mode toggle using Tailwind's dark: variant"

package/dist/cli/templates/blank/src/app/page.tsx

@@ -0,0 +1,10 @@
+export default function Home() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center p-8">
+      <h1 className="text-4xl font-bold tracking-tight">Welcome to your new project</h1>
+      <p className="mt-4 text-lg text-gray-600 dark:text-gray-400">
+        Open the Awel overlay to start building with AI.
+      </p>
+    </main>
+  );
+}

package/dist/cli/templates/blog/AGENT.md

@@ -0,0 +1,26 @@
+# Project Guide
+
+## Overview
+
+A blog application built with Next.js, TypeScript, and Tailwind CSS. Features a post listing page and dynamic post pages.
+
+## Structure
+
+- `src/app/page.tsx` — Blog listing page showing all posts
+- `src/app/blog/[slug]/page.tsx` — Dynamic blog post page
+- `src/lib/posts.ts` — Post data and utility functions
+
+## Conventions
+
+- Use server components by default; add `'use client'` only when needed
+- Style with Tailwind CSS utility classes
+- Keep components in `src/components/`
+- Use TypeScript for all files
+- Posts are stored as data in `src/lib/posts.ts` (replace with a CMS or MDX later)
+
+## Example Prompts
+
+- "Add a new blog post about getting started with Next.js"
+- "Add tags to posts and create a filter by tag"
+- "Add a search bar to filter posts by title"
+- "Create an RSS feed at /feed.xml"

package/dist/cli/templates/blog/src/app/blog/[slug]/page.tsx

@@ -0,0 +1,38 @@
+import Link from 'next/link';
+import { notFound } from 'next/navigation';
+import { getPostBySlug, getAllPosts } from '@/lib/posts';
+
+export function generateStaticParams() {
+  return getAllPosts().map((post) => ({ slug: post.slug }));
+}
+
+export default async function BlogPost({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = getPostBySlug(slug);
+
+  if (!post) {
+    notFound();
+  }
+
+  return (
+    <main className="mx-auto max-w-3xl px-6 py-16">
+      <Link
+        href="/"
+        className="text-sm text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200"
+      >
+        &larr; Back to blog
+      </Link>
+      <article className="mt-8">
+        <time className="text-sm text-gray-500 dark:text-gray-400">
+          {post.date}
+        </time>
+        <h1 className="mt-2 text-4xl font-bold tracking-tight">
+          {post.title}
+        </h1>
+        <div className="prose prose-gray mt-8 dark:prose-invert">
+          <p>{post.content}</p>
+        </div>
+      </article>
+    </main>
+  );
+}

package/dist/cli/templates/blog/src/app/page.tsx

@@ -0,0 +1,35 @@
+import Link from 'next/link';
+import { getAllPosts } from '@/lib/posts';
+
+export default function BlogHome() {
+  const posts = getAllPosts();
+
+  return (
+    <main className="mx-auto max-w-3xl px-6 py-16">
+      <h1 className="text-4xl font-bold tracking-tight">Blog</h1>
+      <p className="mt-4 text-gray-600 dark:text-gray-400">
+        Thoughts, ideas, and tutorials.
+      </p>
+      <div className="mt-12 space-y-10">
+        {posts.map((post) => (
+          <article key={post.slug}>
+            <time className="text-sm text-gray-500 dark:text-gray-400">
+              {post.date}
+            </time>
+            <h2 className="mt-1 text-xl font-semibold">
+              <Link
+                href={`/blog/${post.slug}`}
+                className="hover:underline"
+              >
+                {post.title}
+              </Link>
+            </h2>
+            <p className="mt-2 text-gray-600 dark:text-gray-400">
+              {post.excerpt}
+            </p>
+          </article>
+        ))}
+      </div>
+    </main>
+  );
+}

package/dist/cli/templates/blog/src/lib/posts.ts

@@ -0,0 +1,42 @@
+export interface Post {
+  slug: string;
+  title: string;
+  date: string;
+  excerpt: string;
+  content: string;
+}
+
+const posts: Post[] = [
+  {
+    slug: 'getting-started',
+    title: 'Getting Started with Awel',
+    date: '2025-01-15',
+    excerpt: 'Learn how to set up your first project with Awel and Next.js.',
+    content:
+      'Awel is an AI-powered development overlay for Next.js. It helps you build, modify, and understand your code with an interactive AI assistant. To get started, run npx awel dev in your project directory and look for the floating button in the bottom-right corner.',
+  },
+  {
+    slug: 'building-with-ai',
+    title: 'Building with AI Assistance',
+    date: '2025-01-10',
+    excerpt: 'How AI-assisted development can speed up your workflow.',
+    content:
+      'AI-assisted development is transforming how we build software. With tools like Awel, you can describe what you want to build in natural language, and the AI will help you write the code. This approach is especially powerful for scaffolding new features, debugging issues, and learning new frameworks.',
+  },
+  {
+    slug: 'nextjs-best-practices',
+    title: 'Next.js Best Practices',
+    date: '2025-01-05',
+    excerpt: 'Tips and patterns for building performant Next.js applications.',
+    content:
+      'Next.js provides many built-in optimizations, but there are additional patterns you can follow. Use server components by default and only add the use client directive when you need interactivity. Leverage the Image component for automatic optimization. Use dynamic imports for heavy components that are not needed on initial load.',
+  },
+];
+
+export function getAllPosts(): Post[] {
+  return posts.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
+}
+
+export function getPostBySlug(slug: string): Post | undefined {
+  return posts.find((post) => post.slug === slug);
+}

package/dist/cli/templates/dashboard/AGENT.md

@@ -0,0 +1,26 @@
+# Project Guide
+
+## Overview
+
+A dashboard application built with Next.js, TypeScript, and Tailwind CSS. Features a sidebar navigation and stats cards.
+
+## Structure
+
+- `src/app/page.tsx` — Dashboard main page with stats overview
+- `src/app/layout.tsx` — Root layout with sidebar
+- `src/components/Sidebar.tsx` — Sidebar navigation component
+- `src/components/StatsCard.tsx` — Reusable stats card component
+
+## Conventions
+
+- Use server components by default; add `'use client'` only when needed
+- Style with Tailwind CSS utility classes
+- Keep components in `src/components/`
+- Use TypeScript for all files
+
+## Example Prompts
+
+- "Add a new page for user settings at /settings"
+- "Add a chart component to the dashboard showing weekly data"
+- "Create a data table component with sorting"
+- "Add a notification bell icon to the sidebar header"

package/dist/cli/templates/dashboard/src/app/layout.tsx

@@ -0,0 +1,28 @@
+import type { Metadata } from 'next';
+import { Inter } from 'next/font/google';
+import './globals.css';
+import { Sidebar } from '@/components/Sidebar';
+
+const inter = Inter({ subsets: ['latin'] });
+
+export const metadata: Metadata = {
+  title: 'Dashboard',
+  description: 'Dashboard application built with Awel',
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body className={inter.className}>
+        <div className="flex min-h-screen">
+          <Sidebar />
+          <main className="flex-1 p-8">{children}</main>
+        </div>
+      </body>
+    </html>
+  );
+}

package/dist/cli/templates/dashboard/src/app/page.tsx

@@ -0,0 +1,30 @@
+import { StatsCard } from '@/components/StatsCard';
+
+const stats = [
+  { title: 'Total Users', value: '2,847', change: '+12.5%', trend: 'up' as const },
+  { title: 'Revenue', value: '$45,231', change: '+8.2%', trend: 'up' as const },
+  { title: 'Active Sessions', value: '1,024', change: '-3.1%', trend: 'down' as const },
+  { title: 'Conversion Rate', value: '3.24%', change: '+1.8%', trend: 'up' as const },
+];
+
+export default function Dashboard() {
+  return (
+    <div>
+      <h1 className="text-2xl font-bold">Dashboard</h1>
+      <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">
+        Welcome back. Here&apos;s an overview of your metrics.
+      </p>
+      <div className="mt-8 grid gap-6 sm:grid-cols-2 lg:grid-cols-4">
+        {stats.map((stat) => (
+          <StatsCard key={stat.title} {...stat} />
+        ))}
+      </div>
+      <div className="mt-8 rounded-xl border border-gray-200 p-6 dark:border-gray-800">
+        <h2 className="text-lg font-semibold">Recent Activity</h2>
+        <p className="mt-2 text-sm text-gray-500 dark:text-gray-400">
+          No recent activity to display. Ask Awel to add a data table or chart here.
+        </p>
+      </div>
+    </div>
+  );
+}

package/dist/cli/templates/dashboard/src/components/Sidebar.tsx

@@ -0,0 +1,31 @@
+const navItems = [
+  { label: 'Dashboard', href: '/', icon: '📊' },
+  { label: 'Analytics', href: '/analytics', icon: '📈' },
+  { label: 'Users', href: '/users', icon: '👥' },
+  { label: 'Settings', href: '/settings', icon: '⚙️' },
+];
+
+export function Sidebar() {
+  return (
+    <aside className="flex w-64 flex-col border-r border-gray-200 bg-gray-50 dark:border-gray-800 dark:bg-gray-900">
+      <div className="flex h-16 items-center px-6">
+        <span className="text-lg font-bold">MyApp</span>
+      </div>
+      <nav className="flex-1 px-4 py-4">
+        <ul className="space-y-1">
+          {navItems.map((item) => (
+            <li key={item.href}>
+              <a
+                href={item.href}
+                className="flex items-center gap-3 rounded-lg px-3 py-2 text-sm font-medium text-gray-700 hover:bg-gray-200 dark:text-gray-300 dark:hover:bg-gray-800"
+              >
+                <span>{item.icon}</span>
+                {item.label}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </aside>
+  );
+}

package/dist/cli/templates/dashboard/src/components/StatsCard.tsx

@@ -0,0 +1,24 @@
+interface StatsCardProps {
+  title: string;
+  value: string;
+  change: string;
+  trend: 'up' | 'down';
+}
+
+export function StatsCard({ title, value, change, trend }: StatsCardProps) {
+  return (
+    <div className="rounded-xl border border-gray-200 p-6 dark:border-gray-800">
+      <p className="text-sm text-gray-600 dark:text-gray-400">{title}</p>
+      <p className="mt-2 text-3xl font-bold">{value}</p>
+      <p
+        className={`mt-2 text-sm font-medium ${
+          trend === 'up'
+            ? 'text-green-600 dark:text-green-400'
+            : 'text-red-600 dark:text-red-400'
+        }`}
+      >
+        {change}
+      </p>
+    </div>
+  );
+}

package/dist/cli/templates/landing/AGENT.md

@@ -0,0 +1,26 @@
+# Project Guide
+
+## Overview
+
+A landing page built with Next.js, TypeScript, and Tailwind CSS. Features a hero section, features grid, and call-to-action.
+
+## Structure
+
+- `src/app/page.tsx` — Main landing page (composes Hero, Features, CTA)
+- `src/components/Hero.tsx` — Hero section with headline and CTA button
+- `src/components/Features.tsx` — Features grid (3 columns)
+- `src/components/CTA.tsx` — Call-to-action section and footer
+
+## Conventions
+
+- Use server components by default; add `'use client'` only when needed
+- Style with Tailwind CSS utility classes
+- Keep components in `src/components/`
+- Use TypeScript for all files
+
+## Example Prompts
+
+- "Change the hero headline and add a subtitle"
+- "Add a fourth feature card about security"
+- "Add a testimonials section between Features and CTA"
+- "Make the CTA section have a gradient background"

package/dist/cli/templates/landing/src/app/page.tsx

@@ -0,0 +1,13 @@
+import { Hero } from '@/components/Hero';
+import { Features } from '@/components/Features';
+import { CTA } from '@/components/CTA';
+
+export default function Home() {
+  return (
+    <main>
+      <Hero />
+      <Features />
+      <CTA />
+    </main>
+  );
+}

package/dist/cli/templates/landing/src/components/CTA.tsx

@@ -0,0 +1,23 @@
+export function CTA() {
+  return (
+    <section id="cta" className="px-6 py-24">
+      <div className="mx-auto max-w-3xl rounded-2xl bg-gray-900 px-8 py-16 text-center dark:bg-gray-800">
+        <h2 className="text-3xl font-bold tracking-tight text-white">
+          Ready to get started?
+        </h2>
+        <p className="mt-4 text-gray-300">
+          Start building your project with AI-assisted development.
+        </p>
+        <a
+          href="#"
+          className="mt-8 inline-block rounded-lg bg-white px-6 py-3 text-sm font-semibold text-gray-900 shadow-sm hover:bg-gray-100"
+        >
+          Start building
+        </a>
+      </div>
+      <footer className="mt-16 text-center text-sm text-gray-500">
+        Built with Awel and Next.js
+      </footer>
+    </section>
+  );
+}

package/dist/cli/templates/landing/src/components/Features.tsx

@@ -0,0 +1,46 @@
+const features = [
+  {
+    title: 'Lightning Fast',
+    description: 'Built on Next.js with optimized rendering and automatic code splitting for peak performance.',
+    icon: '⚡',
+  },
+  {
+    title: 'AI-Powered',
+    description: 'Develop faster with Awel — your AI coding assistant that understands your entire project.',
+    icon: '🤖',
+  },
+  {
+    title: 'Beautiful Design',
+    description: 'Tailwind CSS utility-first styling makes it easy to create responsive, polished interfaces.',
+    icon: '🎨',
+  },
+];
+
+export function Features() {
+  return (
+    <section id="features" className="px-6 py-24">
+      <div className="mx-auto max-w-5xl">
+        <h2 className="text-center text-3xl font-bold tracking-tight">
+          Everything you need
+        </h2>
+        <p className="mt-4 text-center text-gray-600 dark:text-gray-400">
+          Start with a solid foundation and build from there.
+        </p>
+        <div className="mt-16 grid gap-8 sm:grid-cols-2 lg:grid-cols-3">
+          {features.map((feature) => (
+            <div
+              key={feature.title}
+              className="rounded-xl border border-gray-200 p-6 dark:border-gray-800"
+            >
+              <div className="text-3xl">{feature.icon}</div>
+              <h3 className="mt-4 text-lg font-semibold">{feature.title}</h3>
+              <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">
+                {feature.description}
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}

package/dist/cli/templates/landing/src/components/Hero.tsx

@@ -0,0 +1,26 @@
+export function Hero() {
+  return (
+    <section className="flex flex-col items-center justify-center px-6 py-24 text-center">
+      <h1 className="max-w-3xl text-5xl font-bold tracking-tight sm:text-6xl">
+        Build something amazing
+      </h1>
+      <p className="mt-6 max-w-xl text-lg text-gray-600 dark:text-gray-400">
+        A modern landing page template powered by Next.js, Tailwind CSS, and AI-assisted development with Awel.
+      </p>
+      <div className="mt-10 flex gap-4">
+        <a
+          href="#features"
+          className="rounded-lg bg-gray-900 px-6 py-3 text-sm font-semibold text-white shadow-sm hover:bg-gray-800 dark:bg-white dark:text-gray-900 dark:hover:bg-gray-100"
+        >
+          Get started
+        </a>
+        <a
+          href="#cta"
+          className="rounded-lg border border-gray-300 px-6 py-3 text-sm font-semibold text-gray-900 hover:bg-gray-50 dark:border-gray-700 dark:text-white dark:hover:bg-gray-800"
+        >
+          Learn more
+        </a>
+      </div>
+    </section>
+  );
+}

package/dist/cli/templates/portfolio/AGENT.md

@@ -0,0 +1,24 @@
+# Project Guide
+
+## Overview
+
+A portfolio website built with Next.js, TypeScript, and Tailwind CSS. Showcases projects with a card-based layout.
+
+## Structure
+
+- `src/app/page.tsx` — Portfolio main page with intro and project grid
+- `src/components/ProjectCard.tsx` — Reusable project card component
+
+## Conventions
+
+- Use server components by default; add `'use client'` only when needed
+- Style with Tailwind CSS utility classes
+- Keep components in `src/components/`
+- Use TypeScript for all files
+
+## Example Prompts
+
+- "Add a contact form section at the bottom of the page"
+- "Add a skills section showing technologies I know"
+- "Create a project detail page at /projects/[slug]"
+- "Add animation to the project cards on hover"

package/dist/cli/templates/portfolio/src/app/page.tsx

@@ -0,0 +1,50 @@
+import { ProjectCard } from '@/components/ProjectCard';
+
+const projects = [
+  {
+    title: 'Project Alpha',
+    description: 'A full-stack web application built with Next.js and PostgreSQL.',
+    tags: ['Next.js', 'TypeScript', 'PostgreSQL'],
+    href: '#',
+  },
+  {
+    title: 'Project Beta',
+    description: 'A mobile-first e-commerce platform with real-time inventory.',
+    tags: ['React Native', 'Node.js', 'Redis'],
+    href: '#',
+  },
+  {
+    title: 'Project Gamma',
+    description: 'An open-source CLI tool for automating deployment workflows.',
+    tags: ['Go', 'Docker', 'CI/CD'],
+    href: '#',
+  },
+  {
+    title: 'Project Delta',
+    description: 'A real-time collaborative document editor with conflict resolution.',
+    tags: ['WebSocket', 'CRDT', 'React'],
+    href: '#',
+  },
+];
+
+export default function Portfolio() {
+  return (
+    <main className="mx-auto max-w-4xl px-6 py-16">
+      <section className="mb-16">
+        <h1 className="text-4xl font-bold tracking-tight">Hi, I&apos;m a developer</h1>
+        <p className="mt-4 max-w-2xl text-lg text-gray-600 dark:text-gray-400">
+          I build web applications and open-source tools. This portfolio was
+          scaffolded with Awel — ask the AI to customize it for you.
+        </p>
+      </section>
+      <section>
+        <h2 className="text-2xl font-bold">Projects</h2>
+        <div className="mt-8 grid gap-6 sm:grid-cols-2">
+          {projects.map((project) => (
+            <ProjectCard key={project.title} {...project} />
+          ))}
+        </div>
+      </section>
+    </main>
+  );
+}

package/dist/cli/templates/portfolio/src/components/ProjectCard.tsx

@@ -0,0 +1,30 @@
+interface ProjectCardProps {
+  title: string;
+  description: string;
+  tags: string[];
+  href: string;
+}
+
+export function ProjectCard({ title, description, tags, href }: ProjectCardProps) {
+  return (
+    <a
+      href={href}
+      className="group block rounded-xl border border-gray-200 p-6 transition-colors hover:border-gray-400 dark:border-gray-800 dark:hover:border-gray-600"
+    >
+      <h3 className="text-lg font-semibold group-hover:underline">{title}</h3>
+      <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">
+        {description}
+      </p>
+      <div className="mt-4 flex flex-wrap gap-2">
+        {tags.map((tag) => (
+          <span
+            key={tag}
+            className="rounded-full bg-gray-100 px-3 py-1 text-xs font-medium text-gray-700 dark:bg-gray-800 dark:text-gray-300"
+          >
+            {tag}
+          </span>
+        ))}
+      </div>
+    </a>
+  );
+}

package/dist/cli/templates/saas/AGENT.md

@@ -0,0 +1,28 @@
+# Project Guide
+
+## Overview
+
+A SaaS application template built with Next.js, TypeScript, and Tailwind CSS. Includes a marketing landing page, pricing page, and dashboard shell.
+
+## Structure
+
+- `src/app/page.tsx` — SaaS marketing landing page
+- `src/app/pricing/page.tsx` — Pricing page with plan comparison
+- `src/app/dashboard/page.tsx` — Authenticated dashboard shell
+- `src/components/Navbar.tsx` — Top navigation bar
+- `src/components/PricingCard.tsx` — Reusable pricing card component
+
+## Conventions
+
+- Use server components by default; add `'use client'` only when needed
+- Style with Tailwind CSS utility classes
+- Keep components in `src/components/`
+- Use TypeScript for all files
+- The Navbar is shared across marketing pages
+
+## Example Prompts
+
+- "Add a features comparison table to the pricing page"
+- "Create a sign-up form with email and password fields"
+- "Add a testimonials carousel to the landing page"
+- "Build a billing settings page at /dashboard/billing"