alepha 0.11.9 → 0.11.11

package/src/commands/CoreCommands.ts

@@ -0,0 +1,169 @@
+import { access, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { $command, CliProvider } from "@alepha/command";
+import { $inject, t } from "@alepha/core";
+import { $logger } from "@alepha/logger";
+import { ProjectUtils } from "../services/ProjectUtils.ts";
+import { version } from "../version.ts";
+
+export class CoreCommands {
+  protected readonly log = $logger();
+  protected readonly cli = $inject(CliProvider);
+  protected readonly utils = $inject(ProjectUtils);
+
+  /**
+   * Called when no command is provided
+   */
+  public readonly root = $command({
+    root: true,
+    flags: t.object({
+      version: t.optional(
+        t.boolean({
+          description: "Show Alepha CLI version",
+          aliases: ["v"],
+        }),
+      ),
+    }),
+    handler: async ({ flags }) => {
+      if (flags.version) {
+        this.log.info(version);
+        return;
+      }
+
+      this.cli.printHelp();
+    },
+  });
+
+  /**
+   * Create a new Alepha project based on one of the sample projects (for now, only one sample project is available)
+   */
+  public readonly create = $command({
+    name: "create",
+    description: "Create a new Alepha project",
+    aliases: ["new"],
+    args: t.text({
+      title: "name",
+    }),
+    flags: t.object({
+      yarn: t.optional(t.boolean({ description: "Use Yarn package manager" })),
+      pnpm: t.optional(t.boolean({ description: "Use pnpm package manager" })),
+    }),
+    summary: false,
+    handler: async ({ run, args, flags, root }) => {
+      const name = args;
+      const dest = join(root, name);
+
+      try {
+        await access(dest);
+        this.log.error(
+          `Directory "${name}" already exists. Please choose a different project name.`,
+        );
+        return;
+      } catch {
+        // Directory does not exist, proceed
+      }
+
+      let installCmd = "npm install";
+      let execCmd = "npx";
+      if (flags.yarn) {
+        installCmd = "yarn";
+        execCmd = "yarn";
+      } else if (flags.pnpm) {
+        installCmd = "pnpm install";
+        execCmd = "pnpm";
+      }
+
+      await mkdir(dest, { recursive: true }).catch(() => null);
+
+      await run("Downloading sample project", () =>
+        this.utils.downloadSampleProject(dest),
+      );
+
+      if (flags.yarn) {
+        await this.utils.ensureYarn(dest);
+        await run(`cd ${name} && yarn set version stable`, {
+          alias: "Setting Yarn to stable version",
+        });
+      }
+
+      await run(`cd ${name} && ${installCmd}`, {
+        alias: "Installing dependencies",
+      });
+
+      await run(`cd ${name} && npx alepha lint`, {
+        alias: "Linting code",
+      });
+
+      await run(`cd ${name} && npx alepha typecheck`, {
+        alias: "Type checking",
+      });
+
+      await run(`cd ${name} && npx alepha test`, {
+        alias: "Running tests",
+      });
+
+      await run(`cd ${name} && npx alepha build`, {
+        alias: "Building project",
+      });
+
+      this.log.info("");
+      this.log.info(`$ cd ${name} && ${execCmd} alepha dev`.trim());
+      this.log.info("");
+    },
+  });
+
+  /**
+   * Clean the project, removing the "dist" directory
+   */
+  public readonly clean = $command({
+    name: "clean",
+    description: "Clean the project",
+    handler: async ({ run }) => {
+      await run.rm("./dist");
+    },
+  });
+
+  /**
+   * Ensure the project has the necessary Alepha configuration files.
+   * Add the correct dependencies to package.json and install them.
+   */
+  public readonly init = $command({
+    name: "init",
+    description: "Add missing Alepha configuration files to the project",
+    flags: t.object({
+      // TODO:
+      // force: t.boolean({
+      //   description: "If true, all config files will be overwritten",
+      // }),
+      // choose package manager
+      yarn: t.optional(t.boolean({ description: "Use Yarn package manager" })),
+      // choose which dependencies to add
+      api: t.optional(
+        t.boolean({ description: "Include Alepha Server dependencies" }),
+      ),
+      react: t.optional(
+        t.boolean({ description: "Include Alepha React dependencies" }),
+      ),
+      orm: t.optional(
+        t.boolean({ description: "Include Alepha ORM dependencies" }),
+      ),
+    }),
+    handler: async ({ run, flags, root }) => {
+      await run("Ensuring Alepha configuration files", async () => {
+        await this.utils.ensureTsConfig(root);
+        await this.utils.ensurePackageJson(root, flags);
+      });
+
+      if (flags.yarn) {
+        await this.utils.ensureYarn(root);
+        await run("yarn install", {
+          alias: "Installing dependencies with Yarn",
+        });
+      } else {
+        await run("npm install", {
+          alias: "Installing dependencies with npm",
+        });
+      }
+    },
+  });
+}

package/src/commands/DrizzleCommands.ts

@@ -0,0 +1,228 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { $command } from "@alepha/command";
+import { $inject, AlephaError, t } from "@alepha/core";
+import { $logger } from "@alepha/logger";
+import { ProcessRunner } from "../services/ProcessRunner.ts";
+import { ProjectUtils } from "../services/ProjectUtils.ts";
+
+export class DrizzleCommands {
+  log = $logger();
+  runner = $inject(ProcessRunner);
+  utils = $inject(ProjectUtils);
+
+  /**
+   * Check if database migrations are up to date
+   *
+   * - Loads the Alepha instance from the specified entry file.
+   * - Retrieves all repository descriptors to gather database models.
+   * - Reads the last migration snapshot from the migration journal.
+   * - Generates the current database schema representation.
+   * - Compares the current schema with the last snapshot to detect changes.
+   * - If changes are detected, prompts the user to run the migration generation command!
+   */
+  check = $command({
+    name: "db:check-migrations",
+    description: "Verify database migration files are up to date",
+    args: t.optional(
+      t.text({
+        title: "path",
+        description: "Path to the Alepha server entry file",
+      }),
+    ),
+    handler: async ({ args, root }) => {
+      const rootDir = root;
+      this.log.debug(`Using project root: ${rootDir}`);
+      const { alepha } = await this.utils.loadAlephaFromServerEntryFile(
+        rootDir,
+        args,
+      );
+
+      const models: any[] = [];
+      const repositories = alepha.descriptors("repository") as any[];
+      const kit = createRequire(import.meta.url)("drizzle-kit/api");
+      const migrationDir = join(rootDir, "migrations");
+
+      const journalFile = await readFile(
+        `${migrationDir}/meta/_journal.json`,
+        "utf-8",
+      ).catch(() => null);
+
+      if (!journalFile) {
+        this.log.info(`No migration journal found.`);
+        return;
+      }
+
+      const journal = JSON.parse(journalFile);
+
+      const lastMigration = journal.entries[journal.entries.length - 1];
+
+      const lastSnapshot = JSON.parse(
+        await readFile(
+          `${migrationDir}/meta/${String(lastMigration.idx).padStart(4, "0")}_snapshot.json`,
+          "utf-8",
+        ),
+      );
+
+      for (const repository of repositories) {
+        if (!models.includes(repository.table)) {
+          models.push(repository.table);
+        }
+      }
+
+      const now = kit.generateDrizzleJson(models, lastSnapshot.id);
+
+      const migrationStatements = await new Promise<Array<any>>((resolve) => {
+        (async () => {
+          const timer = setTimeout(() => {
+            resolve([{ message: "Migration generation timed out." }]);
+          }, 5000);
+          const statements = await kit.generateMigration(lastSnapshot, now);
+          clearTimeout(timer);
+          resolve(statements);
+        })();
+      });
+
+      if (migrationStatements.length === 0) {
+        this.log.info("No changes detected.");
+        return;
+      }
+
+      this.log.info("");
+      this.log.info("Detected migration statements:");
+      this.log.info("");
+      for (const stmt of migrationStatements) {
+        this.log.info(stmt);
+      }
+      this.log.info("");
+
+      this.log.info(
+        `At least ${migrationStatements.length} change(s) detected.`,
+      );
+      this.log.info(
+        "Please, run 'alepha db:generate' to update the migration files.",
+      );
+      this.log.info("");
+
+      throw new AlephaError("Database migrations are not up to date.");
+    },
+  });
+
+  /**
+   * Generate database migration files
+   *
+   * - Loads the Alepha instance from the specified entry file.
+   * - Retrieves all repository descriptors to gather database models.
+   * - Creates temporary entity definitions based on the current database schema.
+   * - Writes these definitions to a temporary schema file. (node_modules/.db/entities.ts)
+   * - Invokes Drizzle Kit's CLI to generate migration files based on the current schema.
+   */
+  generate = $command({
+    name: "db:generate",
+    description: "Generate migration files based on current database schema",
+    summary: false,
+    args: t.optional(
+      t.text({
+        title: "path",
+        description: "Path to the Alepha server entry file",
+      }),
+    ),
+    handler: async ({ args, root }) => {
+      await this.utils.runDrizzleKitCommand({
+        root,
+        args,
+        command: "generate",
+        logMessage: (providerName, dialect) =>
+          `Generate '${providerName}' migrations (${dialect}) ...`,
+      });
+    },
+  });
+
+  /**
+   * Push database schema changes directly to the database
+   *
+   * - Loads the Alepha instance from the specified entry file.
+   * - Retrieves all repository descriptors to gather database models.
+   * - Creates temporary entity definitions and Drizzle config.
+   * - Invokes Drizzle Kit's push command to apply schema changes directly.
+   */
+  push = $command({
+    name: "db:push",
+    description: "Push database schema changes directly to the database",
+    summary: false,
+    args: t.optional(
+      t.text({
+        title: "path",
+        description: "Path to the Alepha server entry file",
+      }),
+    ),
+    handler: async ({ root, args }) => {
+      await this.utils.runDrizzleKitCommand({
+        root,
+        args,
+        command: "push",
+        logMessage: (providerName, dialect) =>
+          `Push '${providerName}' schema (${dialect}) ...`,
+      });
+    },
+  });
+
+  /**
+   * Apply pending database migrations
+   *
+   * - Loads the Alepha instance from the specified entry file.
+   * - Retrieves all repository descriptors to gather database models.
+   * - Creates temporary entity definitions and Drizzle config.
+   * - Invokes Drizzle Kit's migrate command to apply pending migrations.
+   */
+  migrate = $command({
+    name: "db:migrate",
+    description: "Apply pending database migrations",
+    summary: false,
+    args: t.optional(
+      t.text({
+        title: "path",
+        description: "Path to the Alepha server entry file",
+      }),
+    ),
+    handler: async ({ root, args }) => {
+      await this.utils.runDrizzleKitCommand({
+        root,
+        args,
+        command: "migrate",
+        logMessage: (providerName, dialect) =>
+          `Migrate '${providerName}' database (${dialect}) ...`,
+      });
+    },
+  });
+
+  /**
+   * Launch Drizzle Studio database browser
+   *
+   * - Loads the Alepha instance from the specified entry file.
+   * - Retrieves all repository descriptors to gather database models.
+   * - Creates temporary entity definitions and Drizzle config.
+   * - Invokes Drizzle Kit's studio command to launch the web-based database browser.
+   */
+  studio = $command({
+    name: "db:studio",
+    description: "Launch Drizzle Studio database browser",
+    summary: false,
+    args: t.optional(
+      t.text({
+        title: "path",
+        description: "Path to the Alepha server entry file",
+      }),
+    ),
+    handler: async ({ root, args }) => {
+      await this.utils.runDrizzleKitCommand({
+        root,
+        args,
+        command: "studio",
+        logMessage: (providerName, dialect) =>
+          `Launch Studio for '${providerName}' (${dialect}) ...`,
+      });
+    },
+  });
+}

package/src/commands/VerifyCommands.ts

@@ -0,0 +1,44 @@
+import { $command } from "@alepha/command";
+import { $inject } from "@alepha/core";
+import { ProcessRunner } from "../services/ProcessRunner.ts";
+
+export class VerifyCommands {
+  protected readonly processRunner = $inject(ProcessRunner);
+
+  /**
+   * Run a series of verification commands to ensure code quality and correctness.
+   *
+   * This command runs the following checks in order:
+   * 1. Clean the project
+   * 2. Format the code
+   * 3. Lint the code
+   * 4. Run tests
+   * 5. Type check the code
+   * 8. Build the project
+   * 9. Clean the project again
+   */
+  public readonly verify = $command({
+    name: "verify",
+    description: "Verify the Alepha project",
+    handler: async ({ run }) => {
+      await run("alepha clean");
+      await run("alepha format");
+      await run("alepha lint");
+      await run("alepha test");
+      await run("alepha typecheck");
+      await run("alepha build");
+      await run("alepha clean");
+    },
+  });
+
+  /**
+   * Run TypeScript type checking across the codebase with no emit.
+   */
+  public readonly typecheck = $command({
+    name: "typecheck",
+    description: "Check TypeScript types across the codebase",
+    handler: async () => {
+      await this.processRunner.exec("tsc --noEmit");
+    },
+  });
+}

package/src/commands/ViteCommands.ts

@@ -0,0 +1,119 @@
+import { access, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { $command } from "@alepha/command";
+import { $inject, boot, t } from "@alepha/core";
+import { $logger } from "@alepha/logger";
+import { ProcessRunner } from "../services/ProcessRunner.ts";
+import { ProjectUtils } from "../services/ProjectUtils.ts";
+
+export class ViteCommands {
+  protected readonly log = $logger();
+  protected readonly runner = $inject(ProcessRunner);
+  protected readonly utils = $inject(ProjectUtils);
+
+  public readonly run = $command({
+    name: "run",
+    description: "Run a TypeScript file directly",
+    flags: t.object({
+      watch: t.optional(
+        t.boolean({ description: "Watch file for changes", alias: "w" }),
+      ),
+    }),
+    summary: false,
+    args: t.text({ title: "path", description: "Filepath to run" }),
+    handler: async ({ args, flags, root }) => {
+      await this.utils.ensureTsConfig(root);
+      await this.runner.exec(`tsx ${flags.watch ? "watch " : ""}${args}`);
+    },
+  });
+
+  /**
+   * Will run the project in watch mode.
+   *
+   * - If an index.html file is found in the project root, it will run Vite in dev mode.
+   * - Otherwise, it will look for a server entry file and run it with tsx in watch mode.
+   */
+  public readonly dev = $command({
+    name: "dev",
+    description: "Run the project in development mode",
+    args: t.optional(t.text({ title: "path", description: "Filepath to run" })),
+    handler: async ({ args, root }) => {
+      await this.utils.ensureTsConfig(root);
+      await this.utils.ensurePackageJsonModule(root);
+      const entry = await boot.getServerEntry(root, args);
+      this.log.trace("Entry file found", { entry });
+
+      try {
+        await access(join(root, "index.html"));
+      } catch {
+        this.log.trace("No index.html found, running entry file with tsx");
+        await this.runner.exec(`tsx watch ${entry}`);
+        return;
+      }
+
+      const configPath = await this.utils.getViteConfigPath(
+        root,
+        args ? entry : undefined,
+      );
+      this.log.trace("Vite config found", { configPath });
+      await this.runner.exec(`vite -c=${configPath}`);
+    },
+  });
+
+  public readonly build = $command({
+    name: "build",
+    description: "Build the project for production",
+    args: t.optional(
+      t.text({ title: "path", description: "Filepath to build" }),
+    ),
+    flags: t.object({
+      config: t.optional(
+        t.text({ aliases: ["c"], description: "Path to config file" }),
+      ),
+      stats: t.optional(
+        t.boolean({
+          description: "Generate build stats report",
+        }),
+      ),
+    }),
+    handler: async ({ flags, args }) => {
+      const root = process.cwd();
+      await this.utils.ensureTsConfig(root);
+      await this.utils.ensurePackageJsonModule(root);
+      const entry = await boot.getServerEntry(root, args);
+      this.log.trace("Entry file found", { entry });
+
+      await rm("dist", { recursive: true, force: true });
+
+      // DISABLED FOR NOW (waiting for vite-rolldown)
+      // if (flags.lib) {
+      //   await this.runner.exec(
+      //     `tsdown${flags.config ? ` -c=${flags.config}` : ""}`,
+      //   );
+      //   return;
+      // }
+
+      const configPath = await this.utils.getViteConfigPath(
+        root,
+        args ? entry : undefined,
+      );
+
+      const env: Record<string, string> = {};
+      if (flags.stats) {
+        env.ALEPHA_BUILD_STATS = "true";
+      }
+
+      await this.runner.exec(`vite build -c=${configPath}`, env);
+    },
+  });
+
+  public readonly test = $command({
+    name: "test",
+    description: "Run tests using Vitest",
+    handler: async ({ root }) => {
+      await this.utils.ensureTsConfig(root);
+      const configPath = await this.utils.getViteConfigPath(root);
+      await this.runner.exec(`vitest run -c=${configPath}`);
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import "tsx";
+import { $module, Alepha, run } from "@alepha/core";
+import { BiomeCommands } from "./commands/BiomeCommands.ts";
+import { CoreCommands } from "./commands/CoreCommands.ts";
+import { DrizzleCommands } from "./commands/DrizzleCommands.ts";
+import { VerifyCommands } from "./commands/VerifyCommands.ts";
+import { ViteCommands } from "./commands/ViteCommands.ts";
+import { ProcessRunner } from "./services/ProcessRunner.ts";
+import { version } from "./version.ts";
+
+const AlephaCli = $module({
+  name: "alepha.cli",
+  services: [
+    ProcessRunner,
+    CoreCommands,
+    DrizzleCommands,
+    VerifyCommands,
+    ViteCommands,
+    BiomeCommands,
+  ],
+});
+
+const alepha = Alepha.create({
+  env: {
+    LOG_LEVEL: "alepha.core:warn,info",
+    LOG_FORMAT: "raw",
+    CLI_NAME: "alepha",
+    CLI_DESCRIPTION: `Alepha CLI v${version} - Create and manage Alepha projects.`,
+  },
+});
+
+alepha.with(AlephaCli);
+
+run(alepha);

package/src/services/ProcessRunner.ts

@@ -0,0 +1,89 @@
+import { spawn } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { $logger } from "@alepha/logger";
+
+/**
+ * Service for running external processes with logging support.
+ *
+ * This service wraps Node.js child_process functionality and provides:
+ * - Automatic logging of executed commands
+ * - Promise-based execution
+ * - Inherited stdio for seamless output
+ * - Working directory context
+ * - Config file management in node_modules/.alepha
+ */
+export class ProcessRunner {
+  protected readonly log = $logger();
+
+  /**
+   * Execute a command using npx with inherited stdio.
+   *
+   * @param command - The command to execute (will be passed to npx)
+   * @param env - Optional environment variables to set for the command
+   * @returns Promise that resolves when the process exits
+   *
+   * @example
+   * ```ts
+   * const runner = alepha.inject(ProcessRunner);
+   * await runner.exec("tsx watch src/index.ts");
+   * ```
+   */
+  public async exec(
+    command: string,
+    env: Record<string, string> = {},
+  ): Promise<void> {
+    this.log.debug(`Executing command: npx ${command}`, { cwd: process.cwd() });
+
+    const prog = spawn("npx", command.split(" "), {
+      stdio: "inherit",
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        ...env,
+        NODE_OPTIONS: "--import tsx",
+      },
+    });
+
+    await new Promise<void>((resolve) =>
+      prog.on("exit", () => {
+        resolve();
+      }),
+    );
+  }
+
+  /**
+   * Write a configuration file to node_modules/.alepha directory.
+   *
+   * Creates the .alepha directory if it doesn't exist and writes the file with the given content.
+   *
+   * @param name - The name of the config file to create
+   * @param content - The content to write to the file
+   * @param root - The root directory (defaults to process.cwd())
+   * @returns The absolute path to the created file
+   *
+   * @example
+   * ```ts
+   * const runner = alepha.inject(ProcessRunner);
+   * const configPath = await runner.writeConfigFile("biome.json", biomeConfig);
+   * ```
+   */
+  public async writeConfigFile(
+    name: string,
+    content: string,
+    root = process.cwd(),
+  ): Promise<string> {
+    const dir = join(root, "node_modules", ".alepha");
+
+    await mkdir(dir, {
+      recursive: true,
+    }).catch(() => null);
+
+    const path = join(dir, name);
+    await writeFile(path, content);
+
+    this.log.debug(`Config file written: ${path}`);
+
+    return path;
+  }
+}