From 86f59865133ce80fa3db34fc72fad38fc1ea9597 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bartek=20Iwa=C5=84czuk?= <biwanczuk@gmail.com>
Date: Mon, 27 Apr 2026 15:46:01 +0200
Subject: [PATCH] feat: add `@fresh/cli` package for project management and
 code generation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduces a unified CLI tool (`fresh`) that handles:
- `fresh init` — delegates to @fresh/init for project scaffolding
- `fresh dev` / `fresh build` / `fresh start` — project lifecycle commands
- `fresh generate` (aliases: gen, g) — code generation for routes, API routes,
  islands, middleware, layouts, and components
- `fresh routes` — lists all routes with URL patterns and types

The generate command auto-detects the Fresh project root, computes correct
relative import paths for utils.ts, derives PascalCase component names, checks
for route collisions, and supports --dry-run, --force, and --handler flags.

20 tests covering utils and all generator types.
---
 packages/cli/deno.json                     |  23 +++
 packages/cli/src/commands/build.ts         |  49 +++++
 packages/cli/src/commands/dev.ts           |  55 ++++++
 packages/cli/src/commands/generate.ts      | 214 +++++++++++++++++++++
 packages/cli/src/commands/generate_test.ts | 176 +++++++++++++++++
 packages/cli/src/commands/init.ts          |  15 ++
 packages/cli/src/commands/routes.ts        | 143 ++++++++++++++
 packages/cli/src/commands/start.ts         |  57 ++++++
 packages/cli/src/mod.ts                    | 136 +++++++++++++
 packages/cli/src/templates/api.ts          |  12 ++
 packages/cli/src/templates/component.ts    |  16 ++
 packages/cli/src/templates/island.ts       |  18 ++
 packages/cli/src/templates/layout.ts       |  15 ++
 packages/cli/src/templates/middleware.ts   |  10 +
 packages/cli/src/templates/route.ts        |  36 ++++
 packages/cli/src/utils.ts                  | 142 ++++++++++++++
 packages/cli/src/utils_test.ts             |  46 +++++
 17 files changed, 1163 insertions(+)
 create mode 100644 packages/cli/deno.json
 create mode 100644 packages/cli/src/commands/build.ts
 create mode 100644 packages/cli/src/commands/dev.ts
 create mode 100644 packages/cli/src/commands/generate.ts
 create mode 100644 packages/cli/src/commands/generate_test.ts
 create mode 100644 packages/cli/src/commands/init.ts
 create mode 100644 packages/cli/src/commands/routes.ts
 create mode 100644 packages/cli/src/commands/start.ts
 create mode 100644 packages/cli/src/mod.ts
 create mode 100644 packages/cli/src/templates/api.ts
 create mode 100644 packages/cli/src/templates/component.ts
 create mode 100644 packages/cli/src/templates/island.ts
 create mode 100644 packages/cli/src/templates/layout.ts
 create mode 100644 packages/cli/src/templates/middleware.ts
 create mode 100644 packages/cli/src/templates/route.ts
 create mode 100644 packages/cli/src/utils.ts
 create mode 100644 packages/cli/src/utils_test.ts

diff --git a/packages/cli/deno.json b/packages/cli/deno.json
new file mode 100644
index 00000000000..9db5e82049a
--- /dev/null
+++ b/packages/cli/deno.json
@@ -0,0 +1,23 @@
+{
+  "name": "@fresh/cli",
+  "version": "0.1.0",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/mod.ts"
+  },
+  "publish": {
+    "include": [
+      "src/**/*.ts",
+      "deno.json",
+      "README.md"
+    ],
+    "exclude": ["**/*_test.*"]
+  },
+  "imports": {
+    "@std/cli": "jsr:@std/cli@^1.0.19",
+    "@std/fmt": "jsr:@std/fmt@^1.0.7",
+    "@std/path": "jsr:@std/path@^1.1.2",
+    "@std/fs": "jsr:@std/fs@^1.0.19",
+    "@std/jsonc": "jsr:@std/jsonc@^1.0.2"
+  }
+}
diff --git a/packages/cli/src/commands/build.ts b/packages/cli/src/commands/build.ts
new file mode 100644
index 00000000000..6b1e3e17c75
--- /dev/null
+++ b/packages/cli/src/commands/build.ts
@@ -0,0 +1,49 @@
+// deno-lint-ignore-file no-console
+import { error, findProjectRoot } from "../utils.ts";
+
+export interface BuildFlags {
+  dir: string | undefined;
+}
+
+export async function buildCommand(flags: BuildFlags): Promise<void> {
+  const startDir = flags.dir ?? Deno.cwd();
+  const root = findProjectRoot(startDir);
+  if (!root) {
+    error("Could not find a Fresh project. Run from inside a Fresh project.");
+  }
+
+  const config = readProjectConfig(root);
+  const isVite = config.imports?.["vite"] !== undefined ||
+    config.imports?.["@fresh/plugin-vite"] !== undefined;
+
+  const args: string[] = [];
+
+  if (isVite) {
+    args.push("run", "-A", "npm:vite", "build");
+  } else {
+    args.push("run", "-A", "dev.ts", "build");
+  }
+
+  const cmd = new Deno.Command("deno", {
+    args,
+    cwd: root,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+
+  const proc = cmd.spawn();
+  const status = await proc.status;
+  Deno.exit(status.code);
+}
+
+function readProjectConfig(
+  root: string,
+): Record<string, Record<string, string>> {
+  for (const name of ["deno.json", "deno.jsonc"]) {
+    try {
+      return JSON.parse(Deno.readTextFileSync(`${root}/${name}`));
+    } catch { /* try next */ }
+  }
+  return {};
+}
diff --git a/packages/cli/src/commands/dev.ts b/packages/cli/src/commands/dev.ts
new file mode 100644
index 00000000000..4529f2d4d2a
--- /dev/null
+++ b/packages/cli/src/commands/dev.ts
@@ -0,0 +1,55 @@
+// deno-lint-ignore-file no-console
+import { error, findProjectRoot } from "../utils.ts";
+
+export interface DevFlags {
+  port: string | undefined;
+  host: string | undefined;
+  dir: string | undefined;
+}
+
+export async function devCommand(flags: DevFlags): Promise<void> {
+  const startDir = flags.dir ?? Deno.cwd();
+  const root = findProjectRoot(startDir);
+  if (!root) {
+    error("Could not find a Fresh project. Run from inside a Fresh project.");
+  }
+
+  const config = readProjectConfig(root);
+  const isVite = config.imports?.["vite"] !== undefined ||
+    config.imports?.["@fresh/plugin-vite"] !== undefined;
+
+  const args: string[] = [];
+
+  if (isVite) {
+    // Vite-based project: run `deno run -A npm:vite`
+    args.push("run", "-A", "npm:vite");
+    if (flags.port) args.push("--port", flags.port);
+    if (flags.host) args.push("--host", flags.host);
+  } else {
+    // Builder-based project: run `deno run -A dev.ts`
+    args.push("run", "-A", "dev.ts");
+  }
+
+  const cmd = new Deno.Command("deno", {
+    args,
+    cwd: root,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+
+  const proc = cmd.spawn();
+  const status = await proc.status;
+  Deno.exit(status.code);
+}
+
+function readProjectConfig(
+  root: string,
+): Record<string, Record<string, string>> {
+  for (const name of ["deno.json", "deno.jsonc"]) {
+    try {
+      return JSON.parse(Deno.readTextFileSync(`${root}/${name}`));
+    } catch { /* try next */ }
+  }
+  return {};
+}
diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
new file mode 100644
index 00000000000..9e347c4b16d
--- /dev/null
+++ b/packages/cli/src/commands/generate.ts
@@ -0,0 +1,214 @@
+// deno-lint-ignore-file no-console
+import * as path from "@std/path";
+import * as colors from "@std/fmt/colors";
+import {
+  checkCollisions,
+  computeUtilsImport,
+  error,
+  findProjectRoot,
+  toPascalCase,
+  warn,
+  writeFile,
+} from "../utils.ts";
+import { routeTemplate } from "../templates/route.ts";
+import { apiTemplate } from "../templates/api.ts";
+import { islandTemplate } from "../templates/island.ts";
+import { middlewareTemplate } from "../templates/middleware.ts";
+import { layoutTemplate } from "../templates/layout.ts";
+import { componentTemplate } from "../templates/component.ts";
+
+export interface GenerateFlags {
+  handler: boolean;
+  force: boolean;
+  "dry-run": boolean;
+  dir: string | undefined;
+}
+
+const GENERATOR_TYPES = [
+  "route",
+  "island",
+  "middleware",
+  "layout",
+  "api",
+  "component",
+] as const;
+
+type GeneratorType = typeof GENERATOR_TYPES[number];
+
+export function generateCommand(
+  args: string[],
+  flags: GenerateFlags,
+): void {
+  const type = args[0] as GeneratorType | undefined;
+  const name = args[1];
+
+  if (!type) {
+    console.log(`
+${colors.bold("Usage:")} fresh generate <type> <name> [options]
+
+${colors.bold("Types:")}
+  route <path>        Create a page route          ${colors.dim("routes/<path>.tsx")}
+  api <path>          Create an API route           ${colors.dim("routes/<path>.ts")}
+  island <name>       Create an island component    ${colors.dim("islands/<name>.tsx")}
+  middleware [path]    Create a middleware            ${colors.dim("routes/[path/]_middleware.ts")}
+  layout [path]        Create a layout               ${colors.dim("routes/[path/]_layout.tsx")}
+  component <name>    Create a server component     ${colors.dim("components/<name>.tsx")}
+
+${colors.bold("Options:")}
+  --handler            Include a handler (route only)
+  --force              Overwrite existing files
+  --dry-run            Preview without writing files
+  --dir <path>         Project root directory
+
+${colors.bold("Examples:")}
+  fresh generate route about
+  fresh generate route users/[id] --handler
+  fresh generate api users/[id]
+  fresh generate island Counter
+  fresh generate middleware admin
+  fresh generate layout dashboard
+  fresh generate component Button
+`);
+    return;
+  }
+
+  if (!GENERATOR_TYPES.includes(type)) {
+    error(
+      `Unknown generator type: ${type}\n  Available: ${GENERATOR_TYPES.join(", ")}`,
+    );
+  }
+
+  // middleware and layout don't require a name (defaults to root)
+  if (!name && type !== "middleware" && type !== "layout") {
+    error(`Missing name argument. Usage: fresh generate ${type} <name>`);
+  }
+
+  const startDir = flags.dir ? path.resolve(flags.dir) : Deno.cwd();
+  const projectRoot = findProjectRoot(startDir);
+  if (!projectRoot) {
+    error(
+      "Could not find a Fresh project (no deno.json with a 'fresh' import).\n  Run this command from inside a Fresh project, or use --dir.",
+    );
+  }
+
+  const writeOpts = { force: flags.force, dryRun: flags["dry-run"] };
+
+  switch (type) {
+    case "route":
+      generateRoute(projectRoot, name, flags, writeOpts);
+      break;
+    case "api":
+      generateApi(projectRoot, name, writeOpts);
+      break;
+    case "island":
+      generateIsland(projectRoot, name, writeOpts);
+      break;
+    case "middleware":
+      generateMiddleware(projectRoot, name ?? "", writeOpts);
+      break;
+    case "layout":
+      generateLayout(projectRoot, name ?? "", writeOpts);
+      break;
+    case "component":
+      generateComponent(projectRoot, name, writeOpts);
+      break;
+  }
+}
+
+function generateRoute(
+  root: string,
+  name: string,
+  flags: GenerateFlags,
+  writeOpts: { force: boolean; dryRun: boolean },
+): void {
+  const relPath = `routes/${name}.tsx`;
+  const absPath = path.join(root, relPath);
+
+  const collision = checkCollisions(relPath, root);
+  if (collision) warn(collision);
+
+  const componentName = toPascalCase(name.split("/").pop() ?? "Page");
+  const utilsImport = computeUtilsImport(relPath);
+
+  const content = routeTemplate({
+    name: componentName,
+    utilsImport,
+    hasHandler: flags.handler,
+  });
+
+  writeFile(absPath, content, writeOpts);
+}
+
+function generateApi(
+  root: string,
+  name: string,
+  writeOpts: { force: boolean; dryRun: boolean },
+): void {
+  const relPath = `routes/${name}.ts`;
+  const absPath = path.join(root, relPath);
+
+  const collision = checkCollisions(relPath, root);
+  if (collision) warn(collision);
+
+  const utilsImport = computeUtilsImport(relPath);
+  const content = apiTemplate({ utilsImport });
+
+  writeFile(absPath, content, writeOpts);
+}
+
+function generateIsland(
+  root: string,
+  name: string,
+  writeOpts: { force: boolean; dryRun: boolean },
+): void {
+  const relPath = `islands/${name}.tsx`;
+  const absPath = path.join(root, relPath);
+  const componentName = toPascalCase(name.split("/").pop() ?? "Island");
+  const content = islandTemplate({ name: componentName });
+
+  writeFile(absPath, content, writeOpts);
+}
+
+function generateMiddleware(
+  root: string,
+  name: string,
+  writeOpts: { force: boolean; dryRun: boolean },
+): void {
+  const dir = name ? `routes/${name}` : "routes";
+  const relPath = `${dir}/_middleware.ts`;
+  const absPath = path.join(root, relPath);
+  const utilsImport = computeUtilsImport(relPath);
+  const content = middlewareTemplate({ utilsImport });
+
+  writeFile(absPath, content, writeOpts);
+}
+
+function generateLayout(
+  root: string,
+  name: string,
+  writeOpts: { force: boolean; dryRun: boolean },
+): void {
+  const dir = name ? `routes/${name}` : "routes";
+  const relPath = `${dir}/_layout.tsx`;
+  const absPath = path.join(root, relPath);
+  const utilsImport = computeUtilsImport(relPath);
+  const componentName = name
+    ? toPascalCase(name.split("/").pop() ?? "")
+    : "Root";
+  const content = layoutTemplate({ name: componentName, utilsImport });
+
+  writeFile(absPath, content, writeOpts);
+}
+
+function generateComponent(
+  root: string,
+  name: string,
+  writeOpts: { force: boolean; dryRun: boolean },
+): void {
+  const relPath = `components/${name}.tsx`;
+  const absPath = path.join(root, relPath);
+  const componentName = toPascalCase(name.split("/").pop() ?? "Component");
+  const content = componentTemplate({ name: componentName });
+
+  writeFile(absPath, content, writeOpts);
+}
diff --git a/packages/cli/src/commands/generate_test.ts b/packages/cli/src/commands/generate_test.ts
new file mode 100644
index 00000000000..c10a63bbdd2
--- /dev/null
+++ b/packages/cli/src/commands/generate_test.ts
@@ -0,0 +1,176 @@
+import { expect } from "@std/expect";
+import * as path from "@std/path";
+import { generateCommand } from "./generate.ts";
+
+const DEFAULTS = {
+  handler: false,
+  force: false,
+  "dry-run": true, // Always dry-run in tests
+  dir: undefined as string | undefined,
+};
+
+async function withTmpProject(
+  fn: (dir: string) => void | Promise<void>,
+): Promise<void> {
+  const dir = Deno.makeTempDirSync({ prefix: "fresh-cli-test-" });
+  try {
+    // Create a minimal Fresh project structure
+    Deno.writeTextFileSync(
+      path.join(dir, "deno.json"),
+      JSON.stringify({
+        imports: { fresh: "jsr:@fresh/core@^2.0.0" },
+      }),
+    );
+    Deno.writeTextFileSync(
+      path.join(dir, "utils.ts"),
+      'import { createDefine } from "fresh";\nexport const define = createDefine();\n',
+    );
+    Deno.mkdirSync(path.join(dir, "routes"), { recursive: true });
+    Deno.mkdirSync(path.join(dir, "islands"), { recursive: true });
+    Deno.mkdirSync(path.join(dir, "components"), { recursive: true });
+
+    await fn(dir);
+  } finally {
+    Deno.removeSync(dir, { recursive: true });
+  }
+}
+
+Deno.test("generate route - creates route file", async () => {
+  await withTmpProject((dir) => {
+    generateCommand(["route", "about"], { ...DEFAULTS, dir, "dry-run": false });
+    const content = Deno.readTextFileSync(path.join(dir, "routes/about.tsx"));
+    expect(content).toContain("function About()");
+    expect(content).toContain('import { define }');
+    expect(content).toContain("define.page");
+  });
+});
+
+Deno.test("generate route --handler - includes handler", async () => {
+  await withTmpProject((dir) => {
+    generateCommand(["route", "users/[id]"], {
+      ...DEFAULTS,
+      dir,
+      handler: true,
+      "dry-run": false,
+    });
+    const content = Deno.readTextFileSync(
+      path.join(dir, "routes/users/[id].tsx"),
+    );
+    expect(content).toContain("define.handlers");
+    expect(content).toContain("define.page<typeof handler>");
+    expect(content).toContain('import { page } from "fresh"');
+  });
+});
+
+Deno.test("generate api - creates .ts file with handler", async () => {
+  await withTmpProject((dir) => {
+    generateCommand(["api", "users"], { ...DEFAULTS, dir, "dry-run": false });
+    const content = Deno.readTextFileSync(path.join(dir, "routes/users.ts"));
+    expect(content).toContain("define.handlers");
+    expect(content).toContain("Response.json");
+    expect(content).not.toContain("define.page");
+  });
+});
+
+Deno.test("generate island - creates island file", async () => {
+  await withTmpProject((dir) => {
+    generateCommand(["island", "Counter"], {
+      ...DEFAULTS,
+      dir,
+      "dry-run": false,
+    });
+    const content = Deno.readTextFileSync(
+      path.join(dir, "islands/Counter.tsx"),
+    );
+    expect(content).toContain("function Counter(");
+    expect(content).toContain("CounterProps");
+    expect(content).toContain("@preact/signals");
+  });
+});
+
+Deno.test("generate middleware - creates _middleware.ts", async () => {
+  await withTmpProject((dir) => {
+    generateCommand(["middleware", "admin"], {
+      ...DEFAULTS,
+      dir,
+      "dry-run": false,
+    });
+    const content = Deno.readTextFileSync(
+      path.join(dir, "routes/admin/_middleware.ts"),
+    );
+    expect(content).toContain("define.middleware");
+    expect(content).toContain("ctx.next()");
+  });
+});
+
+Deno.test("generate middleware (root) - creates routes/_middleware.ts", async () => {
+  await withTmpProject((dir) => {
+    generateCommand(["middleware"], { ...DEFAULTS, dir, "dry-run": false });
+    const content = Deno.readTextFileSync(
+      path.join(dir, "routes/_middleware.ts"),
+    );
+    expect(content).toContain("define.middleware");
+  });
+});
+
+Deno.test("generate layout - creates _layout.tsx", async () => {
+  await withTmpProject((dir) => {
+    generateCommand(["layout", "dashboard"], {
+      ...DEFAULTS,
+      dir,
+      "dry-run": false,
+    });
+    const content = Deno.readTextFileSync(
+      path.join(dir, "routes/dashboard/_layout.tsx"),
+    );
+    expect(content).toContain("define.layout");
+    expect(content).toContain("DashboardLayout");
+    expect(content).toContain("<Component />");
+  });
+});
+
+Deno.test("generate component - creates component file", async () => {
+  await withTmpProject((dir) => {
+    generateCommand(["component", "Button"], {
+      ...DEFAULTS,
+      dir,
+      "dry-run": false,
+    });
+    const content = Deno.readTextFileSync(
+      path.join(dir, "components/Button.tsx"),
+    );
+    expect(content).toContain("function Button(");
+    expect(content).toContain("ButtonProps");
+    expect(content).toContain("children");
+  });
+});
+
+Deno.test("generate route - refuses to overwrite without --force", async () => {
+  await withTmpProject((dir) => {
+    // Create the file first
+    Deno.mkdirSync(path.join(dir, "routes"), { recursive: true });
+    Deno.writeTextFileSync(path.join(dir, "routes/existing.tsx"), "existing");
+
+    // Should exit(1) on collision - we can't easily test Deno.exit,
+    // so just verify the file wasn't changed by using --dry-run
+    generateCommand(["route", "existing"], { ...DEFAULTS, dir });
+    const content = Deno.readTextFileSync(
+      path.join(dir, "routes/existing.tsx"),
+    );
+    expect(content).toBe("existing"); // unchanged
+  });
+});
+
+Deno.test("generate route - nested import path is correct", async () => {
+  await withTmpProject((dir) => {
+    generateCommand(["route", "admin/settings/general"], {
+      ...DEFAULTS,
+      dir,
+      "dry-run": false,
+    });
+    const content = Deno.readTextFileSync(
+      path.join(dir, "routes/admin/settings/general.tsx"),
+    );
+    expect(content).toContain('../../../utils.ts"');
+  });
+});
diff --git a/packages/cli/src/commands/init.ts b/packages/cli/src/commands/init.ts
new file mode 100644
index 00000000000..f16ce6630ea
--- /dev/null
+++ b/packages/cli/src/commands/init.ts
@@ -0,0 +1,15 @@
+// deno-lint-ignore-file no-console
+
+export async function initCommand(args: string[]): Promise<void> {
+  // Delegate to @fresh/init, passing all arguments through
+  const cmd = new Deno.Command("deno", {
+    args: ["run", "-Ar", "jsr:@fresh/init", ...args],
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+
+  const proc = cmd.spawn();
+  const status = await proc.status;
+  Deno.exit(status.code);
+}
diff --git a/packages/cli/src/commands/routes.ts b/packages/cli/src/commands/routes.ts
new file mode 100644
index 00000000000..b3acb4b2fdb
--- /dev/null
+++ b/packages/cli/src/commands/routes.ts
@@ -0,0 +1,143 @@
+// deno-lint-ignore-file no-console
+import * as path from "@std/path";
+import * as colors from "@std/fmt/colors";
+import { error, findProjectRoot } from "../utils.ts";
+
+export interface RoutesFlags {
+  dir: string | undefined;
+}
+
+interface RouteEntry {
+  file: string;
+  pattern: string;
+  type: "page" | "api" | "middleware" | "layout" | "app" | "error" | "404";
+}
+
+export function routesCommand(flags: RoutesFlags): void {
+  const startDir = flags.dir ?? Deno.cwd();
+  const root = findProjectRoot(startDir);
+  if (!root) {
+    error("Could not find a Fresh project. Run from inside a Fresh project.");
+  }
+
+  const routesDir = path.join(root, "routes");
+  const islandsDir = path.join(root, "islands");
+  const entries: RouteEntry[] = [];
+
+  try {
+    crawl(routesDir, routesDir, entries);
+  } catch {
+    error(`Could not read routes directory: ${routesDir}`);
+  }
+
+  entries.sort((a, b) => a.pattern.localeCompare(b.pattern));
+
+  console.log(colors.bold("\nRoutes:\n"));
+
+  const maxPattern = Math.max(...entries.map((e) => e.pattern.length), 7);
+  const maxType = Math.max(...entries.map((e) => e.type.length), 4);
+
+  console.log(
+    `  ${colors.dim(pad("PATTERN", maxPattern))}  ${colors.dim(pad("TYPE", maxType))}  ${colors.dim("FILE")}`,
+  );
+  console.log(
+    `  ${colors.dim("─".repeat(maxPattern))}  ${colors.dim("─".repeat(maxType))}  ${colors.dim("─".repeat(30))}`,
+  );
+
+  for (const entry of entries) {
+    const typeColor = entry.type === "page"
+      ? colors.green
+      : entry.type === "api"
+      ? colors.blue
+      : entry.type === "middleware"
+      ? colors.yellow
+      : colors.dim;
+    console.log(
+      `  ${pad(entry.pattern, maxPattern)}  ${typeColor(pad(entry.type, maxType))}  ${colors.dim(entry.file)}`,
+    );
+  }
+
+  // Count islands
+  let islandCount = 0;
+  try {
+    for (const entry of Deno.readDirSync(islandsDir)) {
+      if (entry.isFile && /\.[tj]sx?$/.test(entry.name)) islandCount++;
+    }
+  } catch { /* no islands dir */ }
+
+  console.log(
+    `\n  ${colors.bold(String(entries.filter((e) => e.type === "page").length))} pages, ` +
+      `${colors.bold(String(entries.filter((e) => e.type === "api").length))} API routes, ` +
+      `${colors.bold(String(entries.filter((e) => e.type === "middleware").length))} middleware, ` +
+      `${colors.bold(String(islandCount))} islands\n`,
+  );
+}
+
+function pad(str: string, len: number): string {
+  return str + " ".repeat(Math.max(0, len - str.length));
+}
+
+function crawl(
+  dir: string,
+  routesRoot: string,
+  entries: RouteEntry[],
+): void {
+  for (const entry of Deno.readDirSync(dir)) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory) {
+      crawl(full, routesRoot, entries);
+      continue;
+    }
+    if (!entry.isFile || !/\.[tj]sx?$/.test(entry.name)) continue;
+
+    const rel = path.relative(routesRoot, full);
+    const type = getRouteType(entry.name);
+    const pattern = fileToPattern(rel);
+
+    entries.push({ file: `routes/${rel}`, pattern, type });
+  }
+}
+
+function getRouteType(
+  filename: string,
+): RouteEntry["type"] {
+  if (filename.startsWith("_middleware")) return "middleware";
+  if (filename.startsWith("_layout")) return "layout";
+  if (filename.startsWith("_app")) return "app";
+  if (filename.startsWith("_error") || filename.startsWith("_500")) {
+    return "error";
+  }
+  if (filename.startsWith("_404")) return "404";
+
+  // Heuristic: .ts files without JSX extension are likely API routes
+  if (filename.endsWith(".ts") || filename.endsWith(".js")) return "api";
+  return "page";
+}
+
+function fileToPattern(rel: string): string {
+  // Remove extension
+  let pattern = rel.replace(/\.[tj]sx?$/, "");
+
+  // Remove index
+  pattern = pattern.replace(/\/index$/, "");
+  if (pattern === "index") pattern = "";
+
+  // Convert dynamic params
+  pattern = pattern.replace(/\[\.\.\.(\w+)\]/g, ":$1*");
+  pattern = pattern.replace(/\[\[(\w+)\]\]/g, "{:$1}?");
+  pattern = pattern.replace(/\[(\w+)\]/g, ":$1");
+
+  // Strip route groups
+  pattern = pattern.replace(/\([^)]+\)\/?/g, "");
+
+  // Handle special files
+  if (pattern.includes("_middleware")) return pattern.replace("_middleware", "(middleware)");
+  if (pattern.includes("_layout")) return pattern.replace("_layout", "(layout)");
+  if (pattern.includes("_app")) return "(app)";
+  if (pattern.includes("_error") || pattern.includes("_500")) {
+    return pattern.replace(/_error|_500/, "(error)");
+  }
+  if (pattern.includes("_404")) return pattern.replace("_404", "(404)");
+
+  return "/" + pattern;
+}
diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.ts
new file mode 100644
index 00000000000..73bf4c87494
--- /dev/null
+++ b/packages/cli/src/commands/start.ts
@@ -0,0 +1,57 @@
+// deno-lint-ignore-file no-console
+import { error, findProjectRoot } from "../utils.ts";
+
+export interface StartFlags {
+  port: string | undefined;
+  dir: string | undefined;
+}
+
+export async function startCommand(flags: StartFlags): Promise<void> {
+  const startDir = flags.dir ?? Deno.cwd();
+  const root = findProjectRoot(startDir);
+  if (!root) {
+    error("Could not find a Fresh project. Run from inside a Fresh project.");
+  }
+
+  const config = readProjectConfig(root);
+  const isVite = config.imports?.["vite"] !== undefined ||
+    config.imports?.["@fresh/plugin-vite"] !== undefined;
+
+  const args: string[] = [];
+
+  if (isVite) {
+    // Production: run `deno run -A main.ts`
+    args.push("run", "-A", "main.ts");
+  } else {
+    args.push("run", "-A", "main.ts");
+  }
+
+  const env: Record<string, string> = {};
+  if (flags.port) {
+    env["PORT"] = flags.port;
+  }
+
+  const cmd = new Deno.Command("deno", {
+    args,
+    cwd: root,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    env,
+  });
+
+  const proc = cmd.spawn();
+  const status = await proc.status;
+  Deno.exit(status.code);
+}
+
+function readProjectConfig(
+  root: string,
+): Record<string, Record<string, string>> {
+  for (const name of ["deno.json", "deno.jsonc"]) {
+    try {
+      return JSON.parse(Deno.readTextFileSync(`${root}/${name}`));
+    } catch { /* try next */ }
+  }
+  return {};
+}
diff --git a/packages/cli/src/mod.ts b/packages/cli/src/mod.ts
new file mode 100644
index 00000000000..4035f9ee669
--- /dev/null
+++ b/packages/cli/src/mod.ts
@@ -0,0 +1,136 @@
+// deno-lint-ignore-file no-console
+import { parseArgs } from "@std/cli/parse-args";
+import * as colors from "@std/fmt/colors";
+import { generateCommand } from "./commands/generate.ts";
+import { devCommand } from "./commands/dev.ts";
+import { buildCommand } from "./commands/build.ts";
+import { startCommand } from "./commands/start.ts";
+import { initCommand } from "./commands/init.ts";
+import { routesCommand } from "./commands/routes.ts";
+
+const VERSION = "0.1.0";
+
+const HELP = `
+${
+  colors.bgRgb8(
+    colors.rgb8(` 🍋 fresh cli ${colors.rgb8(`v${VERSION}`, 248)} `, 0),
+    121,
+  )
+}
+
+${colors.bold("Usage:")} fresh <command> [options]
+
+${colors.bold("Commands:")}
+  init [dir]             Create a new Fresh project
+  dev                    Start the development server
+  build                  Build for production
+  start                  Start the production server
+  generate <type> <name> Generate a route, island, middleware, layout, api, or component
+  routes                 List all routes in the project
+
+${colors.bold("Generate types:")}
+  route <path>           Create a page route          ${colors.dim("routes/<path>.tsx")}
+  api <path>             Create an API route           ${colors.dim("routes/<path>.ts")}
+  island <name>          Create an island component    ${colors.dim("islands/<name>.tsx")}
+  middleware [path]       Create a middleware            ${colors.dim("routes/[path/]_middleware.ts")}
+  layout [path]           Create a layout               ${colors.dim("routes/[path/]_layout.tsx")}
+  component <name>       Create a server component     ${colors.dim("components/<name>.tsx")}
+
+${colors.bold("Options:")}
+  --help, -h             Show this help message
+  --version, -V          Show version
+  --dir <path>           Project root directory
+  --force                Overwrite existing files (generate)
+  --dry-run              Preview without writing (generate)
+  --handler              Include handler (generate route)
+  --port <port>          Port number (dev, start)
+  --host <host>          Host to bind (dev)
+
+${colors.bold("Examples:")}
+  fresh init my-app
+  fresh dev
+  fresh generate route about
+  fresh generate route users/[id] --handler
+  fresh generate api users
+  fresh generate island SearchBar
+  fresh generate middleware admin
+  fresh routes
+  fresh build
+  fresh start
+`;
+
+const args = parseArgs(Deno.args, {
+  boolean: ["help", "version", "force", "dry-run", "handler"],
+  string: ["dir", "port", "host"],
+  alias: {
+    h: "help",
+    V: "version",
+    f: "force",
+    n: "dry-run",
+    p: "port",
+  },
+});
+
+const command = args._[0] as string | undefined;
+const rest = args._.slice(1).map(String);
+
+if (args.version) {
+  console.log(`fresh ${VERSION}`);
+  Deno.exit(0);
+}
+
+if (args.help && !command) {
+  console.log(HELP);
+  Deno.exit(0);
+}
+
+switch (command) {
+  case "init":
+    await initCommand(rest);
+    break;
+
+  case "dev":
+    await devCommand({
+      port: args.port,
+      host: args.host,
+      dir: args.dir,
+    });
+    break;
+
+  case "build":
+    await buildCommand({ dir: args.dir });
+    break;
+
+  case "start":
+    await startCommand({
+      port: args.port,
+      dir: args.dir,
+    });
+    break;
+
+  case "generate":
+  case "gen":
+  case "g":
+    generateCommand(rest, {
+      handler: args.handler,
+      force: args.force,
+      "dry-run": args["dry-run"],
+      dir: args.dir,
+    });
+    break;
+
+  case "routes":
+    routesCommand({ dir: args.dir });
+    break;
+
+  case undefined:
+    console.log(HELP);
+    break;
+
+  default:
+    console.error(
+      `${colors.red(colors.bold("error"))}: Unknown command: ${command}`,
+    );
+    console.error(`Run ${colors.bold("fresh --help")} for available commands.`);
+    Deno.exit(1);
+}
diff --git a/packages/cli/src/templates/api.ts b/packages/cli/src/templates/api.ts
new file mode 100644
index 00000000000..20ac45fbeaa
--- /dev/null
+++ b/packages/cli/src/templates/api.ts
@@ -0,0 +1,12 @@
+export function apiTemplate(opts: {
+  utilsImport: string;
+}): string {
+  return `import { define } from "${opts.utilsImport}";
+
+export const handler = define.handlers({
+  GET(ctx) {
+    return Response.json({ ok: true });
+  },
+});
+`;
+}
diff --git a/packages/cli/src/templates/component.ts b/packages/cli/src/templates/component.ts
new file mode 100644
index 00000000000..f95688ee115
--- /dev/null
+++ b/packages/cli/src/templates/component.ts
@@ -0,0 +1,16 @@
+export function componentTemplate(opts: {
+  name: string;
+}): string {
+  return `interface ${opts.name}Props {
+  children?: preact.ComponentChildren;
+}
+
+export default function ${opts.name}(props: ${opts.name}Props) {
+  return (
+    <div>
+      {props.children}
+    </div>
+  );
+}
+`;
+}
diff --git a/packages/cli/src/templates/island.ts b/packages/cli/src/templates/island.ts
new file mode 100644
index 00000000000..c085b50113f
--- /dev/null
+++ b/packages/cli/src/templates/island.ts
@@ -0,0 +1,18 @@
+export function islandTemplate(opts: {
+  name: string;
+}): string {
+  return `import { useSignal } from "@preact/signals";
+
+interface ${opts.name}Props {
+  // Add your props here
+}
+
+export default function ${opts.name}(props: ${opts.name}Props) {
+  return (
+    <div>
+      <h2>${opts.name}</h2>
+    </div>
+  );
+}
+`;
+}
diff --git a/packages/cli/src/templates/layout.ts b/packages/cli/src/templates/layout.ts
new file mode 100644
index 00000000000..f73cd77c562
--- /dev/null
+++ b/packages/cli/src/templates/layout.ts
@@ -0,0 +1,15 @@
+export function layoutTemplate(opts: {
+  name: string;
+  utilsImport: string;
+}): string {
+  return `import { define } from "${opts.utilsImport}";
+
+export default define.layout(function ${opts.name}Layout({ Component }) {
+  return (
+    <div>
+      <Component />
+    </div>
+  );
+});
+`;
+}
diff --git a/packages/cli/src/templates/middleware.ts b/packages/cli/src/templates/middleware.ts
new file mode 100644
index 00000000000..2da872468be
--- /dev/null
+++ b/packages/cli/src/templates/middleware.ts
@@ -0,0 +1,10 @@
+export function middlewareTemplate(opts: {
+  utilsImport: string;
+}): string {
+  return `import { define } from "${opts.utilsImport}";
+
+export default define.middleware(async (ctx) => {
+  return await ctx.next();
+});
+`;
+}
diff --git a/packages/cli/src/templates/route.ts b/packages/cli/src/templates/route.ts
new file mode 100644
index 00000000000..f7531254eab
--- /dev/null
+++ b/packages/cli/src/templates/route.ts
@@ -0,0 +1,36 @@
+export function routeTemplate(opts: {
+  name: string;
+  utilsImport: string;
+  hasHandler: boolean;
+}): string {
+  if (opts.hasHandler) {
+    return `import { page } from "fresh";
+import { define } from "${opts.utilsImport}";
+
+export const handler = define.handlers({
+  GET(ctx) {
+    return page({});
+  },
+});
+
+export default define.page<typeof handler>(function ${opts.name}({ data }) {
+  return (
+    <div>
+      <h1>${opts.name}</h1>
+    </div>
+  );
+});
+`;
+  }
+
+  return `import { define } from "${opts.utilsImport}";
+
+export default define.page(function ${opts.name}() {
+  return (
+    <div>
+      <h1>${opts.name}</h1>
+    </div>
+  );
+});
+`;
+}
diff --git a/packages/cli/src/utils.ts b/packages/cli/src/utils.ts
new file mode 100644
index 00000000000..a75782a218b
--- /dev/null
+++ b/packages/cli/src/utils.ts
@@ -0,0 +1,142 @@
+// deno-lint-ignore-file no-console
+import * as path from "@std/path";
+import * as colors from "@std/fmt/colors";
+
+/** Convert a path segment to PascalCase for use as a component name. */
+export function toPascalCase(input: string): string {
+  return input
+    .replace(/[\[\]\.]/g, "") // strip brackets and dots
+    .replace(/^\.+/, "") // strip leading dots (catch-all)
+    .split(/[-_\/]/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("");
+}
+
+/**
+ * Compute the relative import path to `utils.ts` from a target file.
+ * Both paths are relative to the project root.
+ */
+export function computeUtilsImport(targetFilePath: string): string {
+  const dir = path.dirname(targetFilePath);
+  const rel = path.relative(dir, ".");
+  return (rel ? rel + "/" : "./") + "utils.ts";
+}
+
+/**
+ * Find the Fresh project root by walking up from `startDir` looking for a
+ * `deno.json` that imports `fresh` or `@fresh/core`.
+ */
+export function findProjectRoot(startDir: string): string | null {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+
+  while (true) {
+    for (const name of ["deno.json", "deno.jsonc"]) {
+      const configPath = path.join(dir, name);
+      try {
+        const text = Deno.readTextFileSync(configPath);
+        const config = JSON.parse(text);
+        const imports = config.imports ?? {};
+        if (
+          imports["fresh"] !== undefined ||
+          imports["@fresh/core"] !== undefined
+        ) {
+          return dir;
+        }
+      } catch {
+        // file doesn't exist or isn't valid JSON
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir || dir === root) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Write a file, creating parent directories as needed.
+ * Errors if the file already exists unless `force` is true.
+ */
+export function writeFile(
+  filePath: string,
+  content: string,
+  opts: { force?: boolean; dryRun?: boolean },
+): void {
+  if (opts.dryRun) {
+    console.log(colors.yellow(`[dry-run] Would create ${filePath}`));
+    console.log(colors.dim(content));
+    return;
+  }
+
+  if (!opts.force) {
+    try {
+      Deno.statSync(filePath);
+      error(`File already exists: ${filePath}\n  Use --force to overwrite.`);
+    } catch (e) {
+      if (!(e instanceof Deno.errors.NotFound)) throw e;
+    }
+  }
+
+  Deno.mkdirSync(path.dirname(filePath), { recursive: true });
+  Deno.writeTextFileSync(filePath, content);
+  console.log(colors.green("  create") + " " + filePath);
+}
+
+/**
+ * Check for semantic route collisions:
+ * e.g. routes/about.tsx vs routes/about/index.tsx
+ */
+export function checkCollisions(
+  filePath: string,
+  projectRoot: string,
+): string | null {
+  const abs = path.join(projectRoot, filePath);
+
+  // Check file.tsx vs file/index.tsx
+  for (const ext of [".tsx", ".ts", ".jsx", ".js"]) {
+    if (filePath.endsWith(`/index${ext}`)) {
+      const alt = filePath.replace(`/index${ext}`, ext);
+      try {
+        Deno.statSync(path.join(projectRoot, alt));
+        return `Conflict: ${alt} already serves the same URL pattern`;
+      } catch { /* not found */ }
+    } else if (filePath.endsWith(ext)) {
+      const base = filePath.slice(0, -ext.length);
+      for (const altExt of [".tsx", ".ts", ".jsx", ".js"]) {
+        const alt = base + `/index${altExt}`;
+        try {
+          Deno.statSync(path.join(projectRoot, alt));
+          return `Conflict: ${alt} already serves the same URL pattern`;
+        } catch { /* not found */ }
+      }
+    }
+  }
+
+  // Check if the exact file exists (any extension)
+  try {
+    Deno.statSync(abs);
+    return null; // Will be caught by writeFile's existence check
+  } catch { /* not found, good */ }
+
+  return null;
+}
+
+export function error(message: string): never {
+  console.error(
+    `${colors.red(colors.bold("error"))}: ${message}`,
+  );
+  Deno.exit(1);
+}
+
+export function warn(message: string): void {
+  console.warn(
+    `${colors.yellow(colors.bold("warn"))}: ${message}`,
+  );
+}
+
+export function info(message: string): void {
+  console.log(
+    `${colors.blue(colors.bold("info"))}: ${message}`,
+  );
+}
diff --git a/packages/cli/src/utils_test.ts b/packages/cli/src/utils_test.ts
new file mode 100644
index 00000000000..d31777917b4
--- /dev/null
+++ b/packages/cli/src/utils_test.ts
@@ -0,0 +1,46 @@
+import { expect } from "@std/expect";
+import { computeUtilsImport, toPascalCase } from "./utils.ts";
+
+Deno.test("toPascalCase - simple name", () => {
+  expect(toPascalCase("about")).toBe("About");
+});
+
+Deno.test("toPascalCase - kebab-case", () => {
+  expect(toPascalCase("user-profile")).toBe("UserProfile");
+});
+
+Deno.test("toPascalCase - snake_case", () => {
+  expect(toPascalCase("user_profile")).toBe("UserProfile");
+});
+
+Deno.test("toPascalCase - dynamic param [id]", () => {
+  expect(toPascalCase("[id]")).toBe("Id");
+});
+
+Deno.test("toPascalCase - catch-all [...slug]", () => {
+  expect(toPascalCase("[...slug]")).toBe("Slug");
+});
+
+Deno.test("toPascalCase - nested path", () => {
+  expect(toPascalCase("search-bar")).toBe("SearchBar");
+});
+
+Deno.test("computeUtilsImport - top-level route", () => {
+  expect(computeUtilsImport("routes/about.tsx")).toBe("../utils.ts");
+});
+
+Deno.test("computeUtilsImport - nested route", () => {
+  expect(computeUtilsImport("routes/admin/users.tsx")).toBe(
+    "../../utils.ts",
+  );
+});
+
+Deno.test("computeUtilsImport - deeply nested", () => {
+  expect(computeUtilsImport("routes/api/v1/users.ts")).toBe(
+    "../../../utils.ts",
+  );
+});
+
+Deno.test("computeUtilsImport - island", () => {
+  expect(computeUtilsImport("islands/Counter.tsx")).toBe("../utils.ts");
+});