alepha 0.18.2 → 0.18.3

package/src/cli/core/services/PackageManagerUtils.ts

@@ -78,39 +78,61 @@ export class PackageManagerUtils {
   /**
    * Detect workspace context when inside a monorepo package.
    *
-   * Checks if we're inside a workspace package (e.g., packages/my-pkg or apps/my-app)
-   * by looking 2 levels up for workspace indicators like lockfiles and config files.
+   * Checks if we're inside a workspace package by walking up to 3 levels
+   * for workspace indicators like lockfiles and config files.
+   * This covers both standard layouts (packages/my-pkg) and deeper nesting
+   * (packages/scope/my-pkg).
    *
    * @param root - The current package directory
    * @returns Workspace context with root path, PM, and config presence
    */
   public async getWorkspaceContext(root: string): Promise<WorkspaceContext> {
-    // Workspace root is 2 levels up (e.g., packages/my-pkg → ..)
-    const workspaceRoot = this.fs.join(root, "..", "..");
+    const noContext: WorkspaceContext = {
+      isPackage: false,
+      workspaceRoot: null,
+      packageManager: null,
+      config: { biomeJson: false, editorconfig: false, tsconfigJson: false },
+    };
+
+    // Walk up 2–3 levels (covers packages/pkg and packages/scope/pkg)
+    for (let depth = 2; depth <= 3; depth++) {
+      const segments = Array.from({ length: depth }, () => "..");
+      const candidate = this.fs.join(root, ...segments);
+
+      // Don't check above filesystem root
+      if (candidate === root) break;
+
+      const result = await this.checkWorkspaceRoot(candidate);
+      if (result) return result;
+    }
 
-    // Check for lockfiles to detect PM
+    return noContext;
+  }
+
+  protected async checkWorkspaceRoot(
+    candidate: string,
+  ): Promise<WorkspaceContext | null> {
     const [hasYarnLock, hasPnpmLock, hasNpmLock, hasBunLock] =
       await Promise.all([
-        this.fs.exists(this.fs.join(workspaceRoot, "yarn.lock")),
-        this.fs.exists(this.fs.join(workspaceRoot, "pnpm-lock.yaml")),
-        this.fs.exists(this.fs.join(workspaceRoot, "package-lock.json")),
-        this.fs.exists(this.fs.join(workspaceRoot, "bun.lock")),
+        this.fs.exists(this.fs.join(candidate, "yarn.lock")),
+        this.fs.exists(this.fs.join(candidate, "pnpm-lock.yaml")),
+        this.fs.exists(this.fs.join(candidate, "package-lock.json")),
+        this.fs.exists(this.fs.join(candidate, "bun.lock")),
       ]);
 
-    // Check for config files
-    const [hasBiome, hasEditorConfig, hasTsConfig, hasWorkspacePackageJson] =
+    const hasLockfile = hasYarnLock || hasPnpmLock || hasNpmLock || hasBunLock;
+    if (!hasLockfile) return null;
+
+    const [hasBiome, hasEditorConfig, hasTsConfig, hasPackageJson] =
       await Promise.all([
-        this.fs.exists(this.fs.join(workspaceRoot, "biome.json")),
-        this.fs.exists(this.fs.join(workspaceRoot, ".editorconfig")),
-        this.fs.exists(this.fs.join(workspaceRoot, "tsconfig.json")),
-        this.fs.exists(this.fs.join(workspaceRoot, "package.json")),
+        this.fs.exists(this.fs.join(candidate, "biome.json")),
+        this.fs.exists(this.fs.join(candidate, ".editorconfig")),
+        this.fs.exists(this.fs.join(candidate, "tsconfig.json")),
+        this.fs.exists(this.fs.join(candidate, "package.json")),
       ]);
 
-    // Determine if this looks like a workspace root
-    const hasLockfile = hasYarnLock || hasPnpmLock || hasNpmLock || hasBunLock;
-    const isPackage = hasLockfile && hasWorkspacePackageJson;
+    if (!hasPackageJson) return null;
 
-    // Detect package manager from lockfile
     let packageManager: "yarn" | "pnpm" | "npm" | "bun" | null = null;
     if (hasYarnLock) packageManager = "yarn";
     else if (hasPnpmLock) packageManager = "pnpm";
@@ -118,8 +140,8 @@ export class PackageManagerUtils {
     else if (hasNpmLock) packageManager = "npm";
 
     return {
-      isPackage,
-      workspaceRoot: isPackage ? workspaceRoot : null,
+      isPackage: true,
+      workspaceRoot: candidate,
       packageManager,
       config: {
         biomeJson: hasBiome,

package/src/cli/core/services/ProjectScaffolder.ts

@@ -1,7 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { basename, dirname } from "node:path";
-import { $inject } from "alepha";
-import { $logger } from "alepha/logger";
+import { $inject, AlephaError } from "alepha";
+import type { RunnerMethod } from "alepha/command";
+import { $logger, ConsoleColorProvider } from "alepha/logger";
 import { FileSystemProvider } from "alepha/system";
 import { cliAssets } from "../assets.ts";
 import { type AgentMdType, agentMd } from "../templates/agentMd.ts";
@@ -39,6 +40,7 @@ import {
  */
 export class ProjectScaffolder {
   protected readonly log = $logger();
+  protected readonly colors = $inject(ConsoleColorProvider);
   protected readonly fs = $inject(FileSystemProvider);
   protected readonly pm = $inject(PackageManagerUtils);
   protected readonly utils = $inject(AlephaCliUtils);
@@ -385,6 +387,216 @@ export class ProjectScaffolder {
     }
   }
 
+  // ===========================================
+  // Full Init Orchestration
+  // ===========================================
+
+  /**
+   * Full project init — scaffolds files, installs deps, sets up PM and git.
+   */
+  async init({
+    run,
+    root,
+    flags,
+    args,
+  }: {
+    run: RunnerMethod;
+    root: string;
+    flags: {
+      pm?: "yarn" | "npm" | "pnpm" | "bun";
+      api?: boolean;
+      react?: boolean;
+      ui?: boolean;
+      auth?: boolean;
+      admin?: boolean;
+      tailwind?: boolean;
+      test?: boolean;
+      force?: boolean;
+    };
+    args?: string;
+  }) {
+    if (args) {
+      root = this.fs.join(root, args);
+      await this.fs.mkdir(root, { force: true });
+    }
+
+    // Flag cascading: --admin → --auth → --ui → --react, --api
+    if (flags.admin) {
+      flags.auth = true;
+    }
+    if (flags.auth) {
+      flags.api = true;
+      flags.ui = true;
+    }
+    if (flags.ui) {
+      flags.react = true;
+    }
+    if (flags.tailwind) {
+      flags.react = true;
+    }
+
+    // When codegen flags are set, target directory must be empty (unless --force)
+    const hasCodegenFlags =
+      flags.admin ||
+      flags.auth ||
+      flags.api ||
+      flags.ui ||
+      flags.react ||
+      flags.tailwind;
+    if (hasCodegenFlags && !flags.force) {
+      const files = await this.fs.ls(root);
+      // Allow a directory that only has package.json (common for monorepo packages)
+      const meaningful = files.filter((f) => f !== "package.json");
+      if (meaningful.length > 0) {
+        throw new AlephaError(
+          `Target directory is not empty (${root}). Use --force to overwrite existing files.`,
+        );
+      }
+    }
+
+    // Detect workspace context (are we inside packages/ or apps/ of a monorepo?)
+    const workspace = await this.pm.getWorkspaceContext(root);
+
+    // Detect agent type: claude CLI → CLAUDE.md, else → AGENTS.md
+    let agentType: "claude" | "agents" | false = false;
+    if (!workspace.isPackage) {
+      const hasClaudeCli = await this.utils.isInstalledAsync("claude");
+      agentType = hasClaudeCli ? "claude" : "agents";
+    }
+
+    const isExpo = await this.pm.hasExpo(root);
+
+    // Get git email for admin auto-promotion (if auth enabled)
+    const adminEmail = flags.auth ? await this.utils.getGitEmail() : undefined;
+
+    const force = !!flags.force;
+
+    await run({
+      name: "ensuring configuration files",
+      handler: async () => {
+        await this.ensureConfig(root, {
+          force,
+          packageJson: { ...flags, isPackage: workspace.isPackage },
+          // Skip workspace-level configs if they exist at workspace root
+          tsconfigJson: !workspace.config.tsconfigJson,
+          biomeJson: !workspace.config.biomeJson,
+          editorconfig: !workspace.config.editorconfig,
+          agentMd: agentType ? { type: agentType } : false,
+        });
+
+        // Create alepha.config.ts with documented options
+        await this.ensureAlephaConfig(root, { force });
+
+        // Create project structure based on flags
+        await this.ensureMainServerTs(root, {
+          api: !!flags.api,
+          react: !!flags.react && !isExpo,
+          force,
+        });
+        if (flags.api) {
+          await this.ensureApiProject(root, {
+            auth: !!flags.auth,
+            adminEmail,
+            force,
+          });
+        }
+        if (flags.react && !isExpo) {
+          await this.ensureWebProject(root, {
+            api: !!flags.api,
+            ui: !!flags.ui,
+            auth: !!flags.auth,
+            admin: !!flags.admin,
+            tailwind: !!flags.tailwind,
+            force,
+          });
+        }
+      },
+    });
+
+    // Use workspace PM if detected, otherwise detect from current root
+    const pmName = await this.pm.getPackageManager(
+      workspace.workspaceRoot ?? root,
+      flags.pm ?? workspace.packageManager ?? undefined,
+    );
+
+    // Only setup PM files if not in a workspace package
+    if (!workspace.isPackage) {
+      if (pmName === "yarn") {
+        await this.pm.ensureYarn(root);
+        await run("yarn set version stable", { root });
+      } else if (pmName === "bun") {
+        await this.pm.ensureBun(root);
+      } else if (pmName === "pnpm") {
+        await this.pm.ensurePnpm(root);
+      } else {
+        await this.pm.ensureNpm(root);
+      }
+    }
+
+    // Run install from workspace root if in a package, otherwise from current root
+    const installRoot = workspace.workspaceRoot ?? root;
+    await run(`${pmName} install`, {
+      alias: `installing dependencies with ${pmName}`,
+      root: installRoot,
+    });
+
+    // Create test directory if --test flag is set (vitest is in package.json)
+    if (flags.test) {
+      await this.ensureTestDir(root);
+    }
+
+    await run(`${pmName} run lint`, {
+      alias: "running linter",
+      root: installRoot,
+    });
+
+    // Initialize git repository if not in a workspace package
+    if (!workspace.isPackage) {
+      const gitInitialized = await this.ensureGitRepo(root, {
+        force,
+      });
+      if (gitInitialized) {
+        await run("git add .", {
+          alias: "staging generated files",
+          root,
+        });
+      }
+    }
+
+    // Don't show success message if no path arg, e.g. just "alepha init" to re-configure current dir
+    if (!args) {
+      return;
+    }
+
+    // We must end the run context in order to log success message
+    run.end();
+
+    // Success message
+    const projectName = args || ".";
+    const pmRun = pmName === "npm" ? "npm run" : pmName;
+    const c = this.colors;
+
+    this.log.info("");
+    this.log.info(`  ${c.set("GREEN", "✓")} Project ready!`);
+    this.log.info("");
+    this.log.info(
+      `  ${c.set("GREY_DARK", "$")} cd ${c.set("CYAN", projectName)}`,
+    );
+    this.log.info(
+      `  ${c.set("GREY_DARK", "$")} ${c.set("CYAN", `${pmRun} dev`)}`,
+    );
+
+    if (adminEmail) {
+      this.log.info("");
+      this.log.info(`  Admin email: ${c.set("GREEN", adminEmail)}`);
+      this.log.info(
+        `  ${c.set("GREY_DARK", "(from git config, change in src/api/AppSecurity.ts)")}`,
+      );
+    }
+
+    this.log.info("");
+  }
+
   // ===========================================
   // Helpers
   // ===========================================

package/src/cli/core/services/ViteUtils.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, join, relative, resolve } from "node:path";
 import { $hook, $inject, type Alepha, AlephaError } from "alepha";
@@ -171,6 +172,60 @@ export class ViteUtils {
     return logger;
   }
 
+  // ---------------------------------------------------------------------------------------------------------------
+  // TSConfig paths plugin
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Vite plugin that reads tsconfig.json `compilerOptions.paths` and converts
+   * them to Vite `resolve.alias` entries. Enables `@/*` → `src/*` style imports
+   * with zero config beyond tsconfig.json.
+   */
+  public createTsconfigPathsPlugin(): Plugin {
+    return {
+      name: "alepha-tsconfig-paths",
+      async config(config) {
+        const root = config.root || process.cwd();
+        const tsconfigPath = join(root, "tsconfig.json");
+
+        let content: string;
+        try {
+          content = await readFile(tsconfigPath, "utf-8");
+        } catch {
+          return;
+        }
+
+        // Strip JSONC comments before parsing
+        const clean = content
+          .replace(/\/\/.*$/gm, "")
+          .replace(/\/\*[\s\S]*?\*\//g, "");
+
+        let tsconfig: any;
+        try {
+          tsconfig = JSON.parse(clean);
+        } catch {
+          return;
+        }
+
+        const paths = tsconfig?.compilerOptions?.paths;
+        if (!paths || typeof paths !== "object") return;
+
+        const alias: Record<string, string> = {};
+        for (const [pattern, targets] of Object.entries(paths)) {
+          if (!Array.isArray(targets) || targets.length === 0) continue;
+          const target = targets[0] as string;
+          const aliasKey = pattern.replace(/\*$/, "");
+          const aliasPath = target.replace(/\*$/, "").replace(/^\.\//, "");
+          const resolved = resolve(root, aliasPath);
+          alias[aliasKey] = aliasKey.endsWith("/") ? `${resolved}/` : resolved;
+        }
+
+        if (Object.keys(alias).length === 0) return;
+        return { resolve: { alias } };
+      },
+    };
+  }
+
   // ---------------------------------------------------------------------------------------------------------------
   // SSR preload plugin
   // ---------------------------------------------------------------------------------------------------------------
@@ -355,6 +410,7 @@ ${style ? `<link rel="stylesheet" href="/${style}" />` : ""}
     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
+    process.env.APP_SECRET ??= "123456"; // avoid warning about missing secret, not used in CLI context
 
     /**
      * 01/26 Vite 7
@@ -366,6 +422,7 @@ ${style ? `<link rel="stylesheet" href="/${style}" />` : ""}
       server: { middlewareMode: true },
       appType: "custom",
       logLevel: "silent",
+      plugins: [this.createTsconfigPathsPlugin()],
     } satisfies InlineConfig);
 
     await this.viteDevServer.ssrLoadModule(opts.entry.server);

package/src/cli/core/tasks/BuildClientTask.ts

@@ -31,7 +31,10 @@ export class BuildClientTask extends BuildTask {
     // Write index.html template for Vite to consume
     const template = this.viteUtils.generateIndexHtml(ctx.entry);
     await this.fs.mkdir(this.fs.join(ctx.root, "node_modules/.alepha"));
-    const indexHtmlPath = this.fs.join(ctx.root, "node_modules/.alepha/index.html");
+    const indexHtmlPath = this.fs.join(
+      ctx.root,
+      "node_modules/.alepha/index.html",
+    );
     await this.fs.writeFile(indexHtmlPath, template);
 
     try {
@@ -61,6 +64,7 @@ export class BuildClientTask extends BuildTask {
     const viteReact = await this.viteUtils.importViteReact();
     if (viteReact) plugins.push(viteReact());
 
+    plugins.push(this.viteUtils.createTsconfigPathsPlugin());
     plugins.push(this.viteUtils.createSsrPreloadPlugin());
 
     if (opts.stats) {
@@ -92,6 +96,7 @@ export class BuildClientTask extends BuildTask {
             entryFileNames: "entry.[hash].js",
             chunkFileNames: "chunk.[hash].js",
             assetFileNames: "asset.[hash][extname]",
+            experimentalMinChunkSize: 5_000,
           },
         },
       },
@@ -120,7 +125,7 @@ export class BuildClientTask extends BuildTask {
     await this.fs.cp(
       "dist/public/node_modules/.alepha/index.html",
       "dist/public/index.html",
-    )
+    );
     await this.fs.rm("dist/public/node_modules", { recursive: true });
   }
 }

package/src/cli/core/tasks/BuildCloudflareTask.ts

@@ -1,9 +1,9 @@
 import { basename } from "node:path";
 import { $inject } from "alepha";
 import { KV_DEFAULT_BINDING } from "alepha/cache";
-import { FileSystemProvider } from "alepha/system";
 import { QUEUE_DEFAULT_BINDING } from "alepha/queue";
 import type { CronProvider, WorkerdCronProvider } from "alepha/scheduler";
+import { FileSystemProvider } from "alepha/system";
 import { ViteUtils } from "../services/ViteUtils.ts";
 import { BuildTask, type BuildTaskContext } from "./BuildTask.ts";
 
@@ -102,19 +102,14 @@ export class BuildCloudflareTask extends BuildTask {
     ];
   }
 
-  protected enhanceCron(
-    ctx: BuildTaskContext,
-    wrangler: WranglerConfig,
-  ): void {
+  protected enhanceCron(ctx: BuildTaskContext, wrangler: WranglerConfig): void {
     if (ctx.alepha.primitives("scheduler").length === 0) {
       return;
     }
 
     let cronProvider: CronProvider | undefined;
     try {
-      cronProvider = ctx.alepha.inject(
-        "CronProvider",
-      ) as WorkerdCronProvider;
+      cronProvider = ctx.alepha.inject("CronProvider") as WorkerdCronProvider;
     } catch {}
 
     const crons = cronProvider?.getCronJobs();
@@ -144,10 +139,7 @@ export class BuildCloudflareTask extends BuildTask {
       return;
     }
 
-    const [dbName, id] = url
-      .replace("d1://", "")
-      .replace("d1:", "")
-      .split(":");
+    const [dbName, id] = url.replace("d1://", "").replace("d1:", "").split(":");
     const binding = BuildCloudflareTask.D1_BINDING;
     wrangler.d1_databases = wrangler.d1_databases || [];
     wrangler.d1_databases.push({

package/src/cli/core/tasks/BuildServerTask.ts

@@ -81,6 +81,7 @@ export class BuildServerTask extends BuildTask {
       plugins.push(viteReact());
     }
 
+    plugins.push(this.viteUtils.createTsconfigPathsPlugin());
     plugins.push(this.viteUtils.createSsrPreloadPlugin());
 
     if (opts.stats) {
@@ -125,6 +126,7 @@ export class BuildServerTask extends BuildTask {
             chunkFileNames: "[hash].js",
             assetFileNames: "[hash][extname]",
             format: "esm",
+            experimentalMinChunkSize: 10_000,
           },
         },
       },