alepha 0.15.1 → 0.15.3

package/src/cli/services/ProjectScaffolder.ts

@@ -1,20 +1,27 @@
 import { basename, dirname } from "node:path";
 import { $inject } from "alepha";
-import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
-import { apiHelloControllerTs } from "../assets/apiHelloControllerTs.ts";
-import { apiIndexTs } from "../assets/apiIndexTs.ts";
-import { biomeJson } from "../assets/biomeJson.ts";
-import { type ClaudeMdOptions, claudeMd } from "../assets/claudeMd.ts";
-import { dummySpecTs } from "../assets/dummySpecTs.ts";
-import { editorconfig } from "../assets/editorconfig.ts";
-import { mainBrowserTs } from "../assets/mainBrowserTs.ts";
-import { mainCss } from "../assets/mainCss.ts";
-import { mainServerTs } from "../assets/mainServerTs.ts";
-import { tsconfigJson } from "../assets/tsconfigJson.ts";
-import { webAppRouterTs } from "../assets/webAppRouterTs.ts";
-import { webHelloComponentTsx } from "../assets/webHelloComponentTsx.ts";
-import { webIndexTs } from "../assets/webIndexTs.ts";
+import { FileSystemProvider } from "alepha/system";
+import {
+  type AgentMdOptions,
+  type AgentMdType,
+  agentMd,
+} from "../templates/agentMd.ts";
+import { apiAppSecurityTs } from "../templates/apiAppSecurityTs.ts";
+import { apiHelloControllerTs } from "../templates/apiHelloControllerTs.ts";
+import { apiIndexTs } from "../templates/apiIndexTs.ts";
+import { biomeJson } from "../templates/biomeJson.ts";
+import { dummySpecTs } from "../templates/dummySpecTs.ts";
+import { editorconfig } from "../templates/editorconfig.ts";
+import { gitignore } from "../templates/gitignore.ts";
+import { mainBrowserTs } from "../templates/mainBrowserTs.ts";
+import { mainCss } from "../templates/mainCss.ts";
+import { mainServerTs } from "../templates/mainServerTs.ts";
+import { tsconfigJson } from "../templates/tsconfigJson.ts";
+import { webAppRouterTs } from "../templates/webAppRouterTs.ts";
+import { webHelloComponentTsx } from "../templates/webHelloComponentTsx.ts";
+import { webIndexTs } from "../templates/webIndexTs.ts";
+import { AlephaCliUtils } from "./AlephaCliUtils.ts";
 import {
   type DependencyModes,
   PackageManagerUtils,
@@ -33,6 +40,7 @@ export class ProjectScaffolder {
   protected readonly log = $logger();
   protected readonly fs = $inject(FileSystemProvider);
   protected readonly pm = $inject(PackageManagerUtils);
+  protected readonly utils = $inject(AlephaCliUtils);
 
   /**
    * Get the app name from the directory name.
@@ -44,7 +52,7 @@ export class ProjectScaffolder {
    */
   public getAppName(root: string): string {
     const dirName = basename(root);
-    const appName = dirName.toLowerCase().replace(/[\s\-_]/g, "");
+    const appName = dirName.toLowerCase().replace(/[\s\-_.\d]/g, "");
     return appName || "app";
   }
 
@@ -55,16 +63,20 @@ export class ProjectScaffolder {
     root: string,
     opts: {
       force?: boolean;
+      /**
+       * Check workspace root for existing config files.
+       */
+      checkWorkspace?: boolean;
       packageJson?: boolean | DependencyModes;
       tsconfigJson?: boolean;
-      indexHtml?: boolean;
       biomeJson?: boolean;
       editorconfig?: boolean;
-      claudeMd?: boolean | ClaudeMdOptions;
+      agentMd?: false | (AgentMdOptions & { type: AgentMdType });
     },
   ): Promise<void> {
     const tasks: Promise<void>[] = [];
     const force = opts.force ?? false;
+    const checkWorkspace = opts.checkWorkspace ?? false;
 
     if (opts.packageJson) {
       tasks.push(
@@ -79,24 +91,14 @@ export class ProjectScaffolder {
     if (opts.tsconfigJson) {
       tasks.push(this.ensureTsConfig(root, { force }));
     }
-    if (opts.indexHtml) {
-      tasks.push(this.ensureReactProject(root, { force }));
-    }
     if (opts.biomeJson) {
-      tasks.push(this.ensureBiomeConfig(root, { force }));
+      tasks.push(this.ensureBiomeConfig(root, { force, checkWorkspace }));
     }
     if (opts.editorconfig) {
-      tasks.push(this.ensureEditorConfig(root, { force }));
+      tasks.push(this.ensureEditorConfig(root, { force, checkWorkspace }));
     }
-    if (opts.claudeMd) {
-      tasks.push(
-        this.ensureClaudeMd(
-          root,
-          typeof opts.claudeMd === "boolean"
-            ? { force }
-            : { ...opts.claudeMd, force },
-        ),
-      );
+    if (opts.agentMd) {
+      tasks.push(this.ensureAgentMd(root, { ...opts.agentMd, force }));
     }
 
     await Promise.all(tasks);
@@ -122,23 +124,95 @@ export class ProjectScaffolder {
 
   public async ensureBiomeConfig(
     root: string,
-    opts: { force?: boolean } = {},
+    opts: { force?: boolean; checkWorkspace?: boolean } = {},
   ): Promise<void> {
+    if (
+      !opts.force &&
+      opts.checkWorkspace &&
+      (await this.existsInParents(root, "biome.json"))
+    ) {
+      return;
+    }
     await this.ensureFile(root, "biome.json", biomeJson(), opts.force);
   }
 
   public async ensureEditorConfig(
     root: string,
-    opts: { force?: boolean } = {},
+    opts: { force?: boolean; checkWorkspace?: boolean } = {},
   ): Promise<void> {
+    if (
+      !opts.force &&
+      opts.checkWorkspace &&
+      (await this.existsInParents(root, ".editorconfig"))
+    ) {
+      return;
+    }
     await this.ensureFile(root, ".editorconfig", editorconfig(), opts.force);
   }
 
-  public async ensureClaudeMd(
+  /**
+   * Ensure git repository is initialized with .gitignore.
+   *
+   * @returns true if git was initialized, false if already exists or git unavailable
+   */
+  public async ensureGitRepo(
+    root: string,
+    opts: { force?: boolean } = {},
+  ): Promise<boolean> {
+    const gitDir = this.fs.join(root, ".git");
+
+    // Skip if .git already exists
+    if (!opts.force && (await this.fs.exists(gitDir))) {
+      return false;
+    }
+
+    // Check if git is available
+    const hasGit = await this.utils.isInstalledAsync("git");
+    if (!hasGit) {
+      return false;
+    }
+
+    // Initialize git repository
+    await this.utils.exec("git init", { root, global: true });
+
+    // Write .gitignore
+    await this.ensureFile(root, ".gitignore", gitignore(), opts.force);
+
+    return true;
+  }
+
+  public async ensureAgentMd(
+    root: string,
+    options: AgentMdOptions & { type: AgentMdType; force?: boolean },
+  ): Promise<void> {
+    const filename = options.type === "claude" ? "CLAUDE.md" : "AGENTS.md";
+    await this.ensureFile(
+      root,
+      filename,
+      agentMd(options.type, options),
+      options.force,
+    );
+  }
+
+  // ===========================================
+  // Minimal Project Structure
+  // ===========================================
+
+  /**
+   * Ensure src/main.server.ts exists with correct module imports.
+   */
+  public async ensureMainServerTs(
     root: string,
-    options: ClaudeMdOptions & { force?: boolean } = {},
+    opts: { api?: boolean; react?: boolean; force?: boolean } = {},
   ): Promise<void> {
-    await this.ensureFile(root, "CLAUDE.md", claudeMd(options), options.force);
+    const srcDir = this.fs.join(root, "src");
+    await this.fs.mkdir(srcDir, { recursive: true });
+    await this.ensureFile(
+      srcDir,
+      "main.server.ts",
+      mainServerTs({ api: opts.api, react: opts.react }),
+      opts.force,
+    );
   }
 
   // ===========================================
@@ -146,25 +220,16 @@ export class ProjectScaffolder {
   // ===========================================
 
   /**
-   * Ensure src/main.server.ts exists with full API structure.
+   * Ensure API module structure exists.
    *
    * Creates:
-   * - src/main.server.ts (entry point)
    * - src/api/index.ts (API module)
    * - src/api/controllers/HelloController.ts (example controller)
    */
   public async ensureApiProject(
     root: string,
-    opts: { force?: boolean } = {},
+    opts: { auth?: boolean; force?: boolean } = {},
   ): Promise<void> {
-    const srcDir = this.fs.join(root, "src");
-
-    // Don't overwrite existing content unless force is set
-    if (!opts.force && (await this.fs.exists(srcDir))) {
-      const files = await this.fs.ls(srcDir);
-      if (files.length > 0) return;
-    }
-
     const appName = this.getAppName(root);
 
     // Create directories
@@ -173,67 +238,64 @@ export class ProjectScaffolder {
     });
 
     // Create files
-    await this.ensureFile(srcDir, "main.server.ts", mainServerTs(), opts.force);
     await this.ensureFile(
-      srcDir,
-      "api/index.ts",
-      apiIndexTs({ appName }),
+      root,
+      "src/api/index.ts",
+      apiIndexTs({ appName, auth: opts.auth }),
       opts.force,
     );
     await this.ensureFile(
-      srcDir,
-      "api/controllers/HelloController.ts",
+      root,
+      "src/api/controllers/HelloController.ts",
       apiHelloControllerTs(),
       opts.force,
     );
+
+    // Create AppSecurity if auth is enabled
+    if (opts.auth) {
+      await this.ensureFile(
+        root,
+        "src/api/AppSecurity.ts",
+        apiAppSecurityTs(),
+        opts.force,
+      );
+    }
   }
 
   // ===========================================
-  // React Project Structure
+  // Web Project Structure
   // ===========================================
 
   /**
-   * Ensure full React project structure exists.
+   * Ensure web/React project structure exists.
    *
    * Creates:
-   * - src/main.server.ts, src/main.browser.ts
-   * - src/api/index.ts, src/api/controllers/HelloController.ts
+   * - src/main.browser.ts
+   * - src/main.css
    * - src/web/index.ts, src/web/AppRouter.ts, src/web/components/Hello.tsx
    */
-  public async ensureReactProject(
+  public async ensureWebProject(
     root: string,
-    opts: { force?: boolean } = {},
+    opts: {
+      api?: boolean;
+      ui?: boolean;
+      auth?: boolean;
+      admin?: boolean;
+      force?: boolean;
+    } = {},
   ): Promise<void> {
     const appName = this.getAppName(root);
 
     // Create directories
-    await this.fs.mkdir(this.fs.join(root, "src/api/controllers"), {
-      recursive: true,
-    });
     await this.fs.mkdir(this.fs.join(root, "src/web/components"), {
       recursive: true,
     });
 
     // src/main.css
-    await this.ensureFile(root, "src/main.css", mainCss(), opts.force);
-
-    // API structure
-    await this.ensureFile(
-      root,
-      "src/api/index.ts",
-      apiIndexTs({ appName }),
-      opts.force,
-    );
-    await this.ensureFile(
-      root,
-      "src/api/controllers/HelloController.ts",
-      apiHelloControllerTs(),
-      opts.force,
-    );
     await this.ensureFile(
       root,
-      "src/main.server.ts",
-      mainServerTs({ react: true }),
+      "src/main.css",
+      mainCss({ ui: opts.ui }),
       opts.force,
     );
 
@@ -247,13 +309,18 @@ export class ProjectScaffolder {
     await this.ensureFile(
       root,
       "src/web/AppRouter.ts",
-      webAppRouterTs(),
+      webAppRouterTs({
+        api: opts.api,
+        ui: opts.ui,
+        auth: opts.auth,
+        admin: opts.admin,
+      }),
       opts.force,
     );
     await this.ensureFile(
       root,
       "src/web/components/Hello.tsx",
-      webHelloComponentTsx(),
+      webHelloComponentTsx({ auth: opts.auth }),
       opts.force,
     );
     await this.ensureFile(

package/src/cli/services/ViteUtils.ts

@@ -0,0 +1,82 @@
+import { $hook, $inject, type Alepha, AlephaError } from "alepha";
+import { importVite } from "alepha/vite";
+import type { InlineConfig, ViteDevServer } from "vite";
+import { FileSystemProvider } from "../../system/index.ts";
+import type { AppEntry } from "../providers/AppEntryProvider.ts";
+
+export class ViteUtils {
+  protected readonly fs = $inject(FileSystemProvider);
+  protected viteDevServer?: ViteDevServer;
+
+  public generateIndexHtml(entry: AppEntry): string {
+    const style = entry.style;
+    const browser = entry.browser ?? entry.server;
+    return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<title>App</title>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+${style ? `<link rel="stylesheet" href="/${style}" />` : ""}
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="/${browser}"></script>
+</body>
+</html>
+`.trim();
+  }
+
+  /**
+   * We need to close the Vite dev server after build is done.
+   */
+  protected onReady = $hook({
+    on: "ready",
+    priority: "last",
+    handler: async () => {
+      await this.viteDevServer?.close();
+    },
+  });
+
+  protected onStop = $hook({
+    on: "stop",
+    handler: async () => {
+      await this.viteDevServer?.close();
+    },
+  });
+
+  public async runAlepha(opts: {
+    entry: AppEntry;
+    mode: "production" | "development";
+  }): Promise<Alepha> {
+    const { createServer } = await importVite();
+
+    process.env.NODE_ENV = opts.mode;
+    process.env.ALEPHA_CLI_IMPORT = "true"; // signal Alepha App about CLI import, run(alepha) won't start server
+    process.env.LOG_LEVEL ??= "warn"; // reduce log noise
+
+    /**
+     * 01/26 Vite 7
+     * "runnerImport" doesn't work as expected here. (e.g. build docs fail)
+     * -> We still use devServer and ssrLoadModule for now.
+     * -> This is clearly a bad stuff, we need to find better way.
+     */
+    this.viteDevServer = await createServer({
+      server: { middlewareMode: true },
+      appType: "custom",
+      logLevel: "silent",
+    } satisfies InlineConfig);
+
+    await this.viteDevServer.ssrLoadModule(opts.entry.server);
+
+    const alepha: Alepha = (globalThis as any).__alepha;
+    if (!alepha) {
+      throw new AlephaError(
+        "Alepha instance not found after loading entry module",
+      );
+    }
+
+    return alepha;
+  }
+}

package/src/cli/{assets/claudeMd.ts → templates/agentMd.ts}

@@ -1,19 +1,33 @@
-export interface ClaudeMdOptions {
+export interface AgentMdOptions {
   react?: boolean;
   ui?: boolean;
   projectName?: string;
 }
 
-export const claudeMd = (options: ClaudeMdOptions = {}) => {
+export type AgentMdType = "claude" | "agents";
+
+export const agentMd = (
+  type: AgentMdType,
+  options: AgentMdOptions = {},
+): string => {
   const { react = false, projectName = "my-app" } = options;
 
+  const header =
+    type === "claude"
+      ? `# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this Alepha project.`
+      : `# AGENTS.md
+
+This file provides guidance to AI coding assistants when working with this Alepha project.`;
+
   const reactSection = react
     ? `
 ## React & Frontend
 
 ### Pages with \`$page\`
 \`\`\`tsx
-import { $page } from "@alepha/react/router";
+import { $page } from "alepha/react/router";
 import { $client } from "alepha/server/links";
 import type { UserController } from "./UserController.ts";
 
@@ -39,9 +53,9 @@ class AppRouter {
 
 ### React Hooks
 \`\`\`typescript
-import { useAlepha, useClient, useStore, useAction, useInject } from "@alepha/react";
-import { useRouter, useActive } from "@alepha/react/router";
-import { useForm } from "@alepha/react/form";
+import { useAlepha, useClient, useStore, useAction, useInject } from "alepha/react";
+import { useRouter, useActive } from "alepha/react/router";
+import { useForm } from "alepha/react/form";
 \`\`\`
 
 - \`useClient<Controller>()\` - Type-safe API calls
@@ -91,9 +105,7 @@ ${projectName}/
 \`\`\`
 `;
 
-  return `# CLAUDE.md
-
-This file provides guidance to Claude Code when working with this Alepha project.
+  return `${header}
 
 ## Overview
 
@@ -107,10 +119,10 @@ This is an **Alepha** project - a convention-driven TypeScript framework for typ
 
 ## Rules
 
-- Use TypeScript strict mode
+- Use TypeScript strict mode, always check types (\`alepha typecheck\`)
 - Use Biome for formatting (\`alepha lint\`)
-- Use Vitest for testing
-- One file = one class
+- Use Vitest for testing (\`alepha test\`)
+- One file = one class, multiple interfaces/types allowed
 - Primitives are class properties (except \`$entity\`, \`$atom\`)
 - No decorators, no Express/Fastify patterns
 - No manual instantiation - use dependency injection
@@ -118,6 +130,7 @@ This is an **Alepha** project - a convention-driven TypeScript framework for typ
 - Import with file extensions: \`import { User } from "./User.ts"\`
 - Use \`t\` from Alepha for schemas (not Zod)
 - Prefer \`t.text()\` over \`t.string()\` for user input (has default max length, auto-trim, supports lowercase option)
+- One file = one schema (schemas/createUserSchema.ts)
 
 ## Project Structure
 ${projectStructure}
@@ -160,17 +173,12 @@ export const userEntity = $entity({
     id: db.primaryKey(),
     email: t.email(),
     createdAt: db.createdAt(),
-    updatedAt: db.updatedAt(),
   }),
   indexes: [{ column: "email", unique: true }],
 });
 
 class UserService {
-  repo = $repository(userEntity);
-
-  async findById(id: string) {
-    return this.repo.findById(id);
-  }
+  userRepository = $repository(userEntity);
 }
 \`\`\`
 
@@ -180,11 +188,6 @@ import { $inject } from "alepha";
 
 class OrderService {
   userService = $inject(UserService);  // Within same module
-
-  async createOrder(userId: string) {
-    const user = await this.userService.findById(userId);
-    // ...
-  }
 }
 
 // Cross-module: use $client instead of $inject
@@ -250,7 +253,7 @@ ${reactSection}
 | \`$command\` | \`alepha/command\` | CLI commands |${
     react
       ? `
-| \`$page\` | \`@alepha/react/router\` | React pages with SSR |
+| \`$page\` | \`alepha/react/router\` | React pages with SSR |
 | \`$atom\` | \`alepha\` | Global state |`
       : ""
   }
@@ -304,5 +307,15 @@ alepha build     # Build the project
 
 - Full docs: https://alepha.dev/llms.txt
 - Detailed docs: https://alepha.dev/llms-full.txt
+
+## Source Code Access
+
+Full framework source available at \`node_modules/alepha/src/\`.
+
+**IMPORTANT:** When answering questions about Alepha primitives, APIs, or internals:
+1. ALWAYS read the local source code first at \`node_modules/alepha/src/\` or \`node_modules/@alepha/ui/src/\` for UI-related questions
+2. Use \`Glob\` to find relevant files: \`node_modules/alepha/src/**/primitives/$<name>.ts\`
+3. Read the implementation AND the \`.spec.ts\` test files for usage examples
+4. Use external documentation as a fallback if source code is insufficient
 `.trim();
 };

package/src/cli/templates/apiAppSecurityTs.ts

@@ -0,0 +1,11 @@
+export const apiAppSecurityTs = () => {
+  return `
+import { $realm } from "alepha/api/users";
+
+export class AppSecurity {
+  users = $realm({
+    // configure your realm here
+  });
+}
+`.trim();
+};

package/src/cli/templates/apiIndexTs.ts

@@ -0,0 +1,30 @@
+export interface ApiIndexTsOptions {
+  appName?: string;
+  auth?: boolean;
+}
+
+export const apiIndexTs = (options: ApiIndexTsOptions = {}) => {
+  const { appName = "app", auth = false } = options;
+
+  const imports: string[] = ['import { $module } from "alepha";'];
+  const services: string[] = [];
+
+  if (auth) {
+    imports.push('import { AppSecurity } from "./AppSecurity.ts";');
+    services.push("AppSecurity");
+  }
+
+  imports.push(
+    'import { HelloController } from "./controllers/HelloController.ts";',
+  );
+  services.push("HelloController");
+
+  return `
+${imports.join("\n")}
+
+export const ApiModule = $module({
+  name: "${appName}.api",
+  services: [${services.join(", ")}],
+});
+`.trim();
+};

package/src/cli/templates/gitignore.ts

@@ -0,0 +1,39 @@
+export const gitignore = () =>
+  `
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+.vite/
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# IDE
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Test coverage
+coverage/
+
+# Yarn
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+.pnp.*
+`.trim();

package/src/cli/{assets → templates}/mainCss.ts

@@ -1,5 +1,13 @@
-export const mainCss = () =>
-  `
+export interface MainCssOptions {
+  ui?: boolean;
+}
+
+export const mainCss = (options: MainCssOptions = {}) => {
+  if (options.ui) {
+    return `@import "@alepha/ui/styles";`;
+  }
+
+  return `
 * {
   box-sizing: border-box;
   margin: 0;
@@ -22,3 +30,4 @@ body {
   height: 100%;
 }
 `.trim();
+};