alepha 0.15.1 → 0.15.2

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,10 @@ 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/\`.
+Read primitives directly when you need implementation details.
 `.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();
+};

package/src/cli/templates/mainServerTs.ts

@@ -0,0 +1,33 @@
+export interface MainServerTsOptions {
+  api?: boolean;
+  react?: boolean;
+}
+
+export const mainServerTs = (options: MainServerTsOptions = {}) => {
+  const { api = false, react = false } = options;
+
+  const imports: string[] = [];
+  const withs: string[] = [];
+
+  if (api) {
+    imports.push(`import { ApiModule } from "./api/index.ts";`);
+    withs.push(`alepha.with(ApiModule);`);
+  }
+
+  if (react) {
+    imports.push(`import { WebModule } from "./web/index.ts";`);
+    withs.push(`alepha.with(WebModule);`);
+  }
+
+  const importsBlock = imports.length > 0 ? `${imports.join("\n")}\n` : "";
+  const withsBlock = withs.length > 0 ? `\n${withs.join("\n")}` : "";
+
+  return `
+import { Alepha, run } from "alepha";
+${importsBlock}
+const alepha = Alepha.create();
+${withsBlock}
+
+run(alepha);
+`.trim();
+};

package/src/cli/templates/webAppRouterTs.ts

@@ -0,0 +1,50 @@
+export const webAppRouterTs = (options: { api?: boolean; ui?: boolean }) => {
+  const imports: string[] = [];
+  const classMembers: string[] = [];
+
+  // UI import and setup
+  if (options.ui) {
+    imports.push('import { $ui } from "@alepha/ui";');
+  }
+
+  // Page import
+  imports.push('import { $page } from "alepha/react/router";');
+
+  // API imports (only if api flag is set)
+  if (options.api) {
+    imports.push('import { $client } from "alepha/server/links";');
+    imports.push(
+      'import type { HelloController } from "../api/controllers/HelloController.ts";',
+    );
+    classMembers.push("  api = $client<HelloController>();");
+  }
+
+  // UI layout setup
+  if (options.ui) {
+    classMembers.push("  ui = $ui();");
+    classMembers.push(`  layout = $page({
+    parent: this.ui.root,
+    children: () => [this.home],
+  });`);
+  }
+
+  // Home page - with or without loader
+  if (options.api) {
+    classMembers.push(`  home = $page({
+    path: "/",
+    lazy: () => import("./components/Hello.tsx"),
+    loader: () => this.api.hello(),
+  });`);
+  } else {
+    classMembers.push(`  home = $page({
+    path: "/",
+    lazy: () => import("./components/Hello.tsx"),
+  });`);
+  }
+
+  return `${imports.join("\n")}
+
+export class AppRouter {
+${classMembers.join("\n\n")}
+}`;
+};

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

@@ -2,11 +2,11 @@ export const webHelloComponentTsx = () =>
   `import { useState } from "react";
 
 interface Props {
-  message: string;
+  message?: string;
 }
 
 const Hello = (props: Props) => {
-  const [message, setMessage] = useState(props.message);
+  const [message, setMessage] = useState(props.message ?? "");
   return (
     <div>
       <h1>{message}</h1>

package/src/command/helpers/Runner.spec.ts

@@ -3,11 +3,13 @@ import {
   LogDestinationProvider,
   MemoryDestinationProvider,
 } from "alepha/logger";
+import { MemoryShellProvider } from "alepha/system";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { Runner } from "../index.ts";
 
 describe("Runner", () => {
   let mockLogger: MemoryDestinationProvider;
+  let mockShell: MemoryShellProvider;
   let runner: Runner;
 
   beforeEach(async () => {
@@ -22,6 +24,7 @@ describe("Runner", () => {
     // Create a new MockLogger and Runner for each test to ensure isolation
     runner = alepha.inject(Runner);
     mockLogger = alepha.inject(MemoryDestinationProvider);
+    mockShell = alepha.inject(MemoryShellProvider);
   });
 
   afterEach(() => {
@@ -91,6 +94,7 @@ describe("Runner", () => {
   });
 
   test("should throw and log an error for a failing shell command", async () => {
+    mockShell.errors.set("exit 1", "Command failed with exit code 1");
     await expect(runner.run(`exit 1`)).rejects.toThrow("Task 'exit 1' failed");
   });
 

package/src/command/helpers/Runner.ts

@@ -1,7 +1,7 @@
-import { exec } from "node:child_process";
 import { cp, glob, rm } from "node:fs/promises";
 import { $inject, Alepha } from "alepha";
 import { $logger } from "alepha/logger";
+import { ShellProvider } from "alepha/system";
 import { CommandError } from "../errors/CommandError.ts";
 import { PrettyPrint } from "./PrettyPrint.ts";
 
@@ -42,6 +42,7 @@ export class Runner {
   protected readonly startTime: number = Date.now();
   protected readonly prettyPrint = $inject(PrettyPrint);
   protected readonly alepha = $inject(Alepha);
+  protected readonly shell = $inject(ShellProvider);
   public readonly run: RunnerMethod;
   protected cliName = "";
   protected commandName = "";
@@ -152,26 +153,7 @@ export class Runner {
     cmd: string,
     opts: { root?: string } = {},
   ): Promise<string> {
-    return await new Promise<string>((resolve, reject) => {
-      exec(
-        cmd,
-        {
-          cwd: opts.root,
-          env: {
-            ...process.env,
-            LOG_FORMAT: "pretty",
-          },
-        },
-        (err, stdout) => {
-          if (err) {
-            err.stdout = stdout;
-            reject(err);
-          } else {
-            resolve(stdout);
-          }
-        },
-      );
-    });
+    return this.shell.run(cmd, { root: opts.root, capture: true });
   }
 
   /**

package/src/command/index.ts

@@ -19,12 +19,20 @@ export * from "./providers/CliProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * This module provides a powerful way to build command-line interfaces
- * directly within your Alepha application, using declarative primitives.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | tooling | rare | stable |
  *
- * It allows you to define commands using the `$command` primitive.
+ * Declarative CLI command framework.
+ *
+ * **Features:**
+ * - CLI command definitions
+ * - Interactive CLI prompts
+ * - Command execution
+ * - Formatted colored output
+ * - Environment variable utilities
+ * - Schema validation for CLI arguments
  *
- * @see {@link $command}
  * @module alepha.command
  */
 export const AlephaCommand = $module({