alepha 0.11.7 → 0.11.10

package/src/commands/CoreCommands.ts

@@ -0,0 +1,266 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { $command, CliProvider } from "@alepha/command";
+import { $inject, AlephaError, t } from "@alepha/core";
+import { $logger } from "@alepha/logger";
+import { pipeline } from "stream/promises";
+import * as tar from "tar";
+import { tsconfigJson } from "../assets/tsconfigJson.ts";
+import { version } from "../version.ts";
+
+export class CoreCommands {
+  protected readonly log = $logger();
+  protected readonly cli = $inject(CliProvider);
+
+  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();
+    },
+  });
+
+  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 }) => {
+      const name = args;
+      const root = process.cwd();
+      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.downloadSampleProject(dest),
+      );
+
+      if (flags.yarn) {
+        await this.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("");
+    },
+  });
+
+  public readonly clean = $command({
+    name: "clean",
+    description: "Clean the project",
+    handler: async ({ run }) => {
+      await run.rm("./dist");
+    },
+  });
+
+  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",
+      // }),
+      yarn: t.boolean({ description: "Use Yarn package manager" }),
+      api: t.boolean({ description: "Include Alepha Server dependencies" }),
+      react: t.boolean({ description: "Include Alepha React dependencies" }),
+    }),
+    handler: async ({ run, flags }) => {
+      const root = process.cwd();
+
+      await this.ensureTsConfig(root);
+      await this.ensurePackageJson(root, flags);
+
+      if (flags.yarn) {
+        await this.ensureYarn(root);
+      } else {
+        await run("npm install", {
+          alias: "Installing dependencies with npm",
+        });
+      }
+    },
+  });
+
+  public async ensureYarn(root: string) {
+    const tsconfigPath = join(root, ".yarnrc.yml");
+    try {
+      await access(tsconfigPath);
+    } catch {
+      await writeFile(tsconfigPath, "nodeLinker: node-modules");
+    }
+  }
+
+  public generatePackageJsonContent(modes: { api?: boolean; react?: boolean }) {
+    const dependencies: Record<string, string> = {
+      "@alepha/core": `^${version}`,
+      "@alepha/logger": `^${version}`,
+      "@alepha/datetime": `^${version}`,
+    };
+
+    const devDependencies: Record<string, string> = {
+      alepha: `^${version}`,
+      "@alepha/vite": `^${version}`,
+    };
+
+    if (modes.api) {
+      dependencies["@alepha/server"] = `^${version}`;
+      dependencies["@alepha/server-swagger"] = `^${version}`;
+      dependencies["@alepha/server-multipart"] = `^${version}`;
+    }
+
+    if (modes.react) {
+      dependencies["@alepha/server"] = `^${version}`;
+      dependencies["@alepha/server-links"] = `^${version}`;
+      dependencies["@alepha/react"] = `^${version}`;
+      dependencies.react = "^19.2.0";
+      devDependencies["@types/react"] = "^19.0.0";
+    }
+
+    return {
+      dependencies,
+      devDependencies,
+      scripts: {
+        dev: "alepha dev",
+        build: "alepha build",
+      },
+    };
+  }
+
+  public async ensurePackageJson(
+    root: string,
+    modes: { api?: boolean; react?: boolean },
+  ) {
+    const packageJsonPath = join(root, "package.json");
+    try {
+      await access(packageJsonPath);
+    } catch (error) {
+      this.log.info("No package.json found. Creating one...");
+      await writeFile(
+        packageJsonPath,
+        JSON.stringify(this.generatePackageJsonContent(modes), null, 2),
+      );
+      return;
+    }
+
+    const content = await readFile(packageJsonPath, "utf8");
+    const packageJson = JSON.parse(content);
+    if (!packageJson.type || packageJson.type !== "module") {
+      packageJson.type = "module";
+    }
+    const newPackageJson = this.generatePackageJsonContent(modes);
+
+    packageJson.type = "module";
+    packageJson.dependencies ??= {};
+    packageJson.devDependencies ??= {};
+    packageJson.scripts ??= {};
+
+    Object.assign(packageJson.dependencies, newPackageJson.dependencies);
+    Object.assign(packageJson.devDependencies, newPackageJson.devDependencies);
+    Object.assign(packageJson.scripts, newPackageJson.scripts);
+
+    await writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2));
+  }
+
+  public async ensureTsConfig(root = process.cwd()) {
+    const tsconfigPath = join(root, "tsconfig.json");
+    try {
+      await access(tsconfigPath);
+    } catch {
+      this.log.info("Missing tsconfig.json detected. Creating one...");
+      await writeFile(tsconfigPath, tsconfigJson);
+    }
+  }
+
+  public async downloadSampleProject(targetDir: string) {
+    const url = "https://api.github.com/repos/feunard/alepha/tarball/main";
+    const response = await fetch(url, {
+      headers: {
+        "User-Agent": "Alepha-CLI", // GitHub API requires User-Agent
+      },
+    });
+
+    if (!response.ok) {
+      throw new AlephaError(`Failed to download: ${response.statusText}`);
+    }
+
+    const tarStream = Readable.fromWeb(response.body as any);
+    await pipeline(
+      tarStream,
+      tar.extract({
+        cwd: targetDir, // Extract to target directory
+        strip: 3, // Remove feunard-alepha-<hash>/apps/starter prefix
+        filter: (path) => {
+          // Only extract files from apps/starter/
+          const parts = path.split("/");
+          return (
+            parts.length >= 3 && parts[1] === "apps" && parts[2] === "starter"
+          );
+        },
+      }),
+    );
+  }
+}

package/src/commands/DrizzleCommands.ts

@@ -0,0 +1,403 @@
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { $command } from "@alepha/command";
+import { $inject, Alepha, AlephaError, boot, t } from "@alepha/core";
+import { $logger } from "@alepha/logger";
+import type { RepositoryProvider } from "@alepha/postgres";
+import { tsImport } from "tsx/esm/api";
+import { ProcessRunner } from "../services/ProcessRunner.ts";
+
+export class DrizzleCommands {
+  log = $logger();
+  runner = $inject(ProcessRunner);
+
+  flags = t.object({
+    root: t.text({ description: "Project root", default: "." }),
+  });
+
+  /**
+   * 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",
+    flags: this.flags,
+    args: t.optional(
+      t.text({
+        title: "path",
+        description: "Path to the Alepha server entry file",
+      }),
+    ),
+    handler: async ({ flags, args }) => {
+      const rootDir = join(process.cwd(), flags.root);
+      this.log.debug(`Using project root: ${rootDir}`);
+      const { alepha } = await this.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,
+    flags: this.flags,
+    args: t.optional(
+      t.text({
+        title: "path",
+        description: "Path to the Alepha server entry file",
+      }),
+    ),
+    handler: async ({ flags, args }) => {
+      await this.runDrizzleKitCommand({
+        flags,
+        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,
+    flags: this.flags,
+    args: t.optional(
+      t.text({
+        title: "path",
+        description: "Path to the Alepha server entry file",
+      }),
+    ),
+    handler: async ({ flags, args }) => {
+      await this.runDrizzleKitCommand({
+        flags,
+        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,
+    flags: this.flags,
+    args: t.optional(
+      t.text({
+        title: "path",
+        description: "Path to the Alepha server entry file",
+      }),
+    ),
+    handler: async ({ flags, args }) => {
+      await this.runDrizzleKitCommand({
+        flags,
+        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,
+    flags: this.flags,
+    args: t.optional(
+      t.text({
+        title: "path",
+        description: "Path to the Alepha server entry file",
+      }),
+    ),
+    handler: async ({ flags, args }) => {
+      await this.runDrizzleKitCommand({
+        flags,
+        args,
+        command: "studio",
+        logMessage: (providerName, dialect) =>
+          `Launch Studio for '${providerName}' (${dialect}) ...`,
+      });
+    },
+  });
+
+  /**
+   * Run a drizzle-kit command for all database providers
+   */
+  protected async runDrizzleKitCommand(options: {
+    flags: { root: string };
+    args?: string;
+    command: string;
+    logMessage: (providerName: string, dialect: string) => string;
+  }): Promise<void> {
+    const rootDir = join(process.cwd(), options.flags.root);
+    this.log.debug(`Using project root: ${rootDir}`);
+
+    const { alepha, entry } = await this.loadAlephaFromServerEntryFile(
+      rootDir,
+      options.args,
+    );
+
+    const kit = this.getKitFromAlepha(alepha);
+    const repositoryProvider =
+      alepha.inject<RepositoryProvider>("RepositoryProvider");
+    const accepted = new Set<string>([]);
+
+    for (const descriptor of repositoryProvider.getRepositories()) {
+      const provider = descriptor.provider;
+      const providerName = provider.name;
+      const dialect = provider.dialect;
+
+      if (accepted.has(providerName)) {
+        continue;
+      }
+      accepted.add(providerName);
+
+      this.log.info("");
+      this.log.info(options.logMessage(providerName, dialect));
+
+      const drizzleConfigJsPath = await this.prepareDrizzleConfig({
+        kit,
+        provider,
+        providerName,
+        providerUrl: provider.url,
+        dialect,
+        entry,
+        rootDir,
+      });
+
+      await this.runner.exec(
+        `drizzle-kit ${options.command} --config=${drizzleConfigJsPath}`,
+      );
+    }
+  }
+
+  /**
+   * Prepare Drizzle configuration files for a provider
+   */
+  protected async prepareDrizzleConfig(options: {
+    kit: any;
+    provider: any;
+    providerName: string;
+    providerUrl: string;
+    dialect: string;
+    entry: string;
+    rootDir: string;
+  }): Promise<string> {
+    const models = Object.keys(options.kit.getModels(options.provider));
+    const entitiesJs = this.generateEntitiesJs(
+      options.entry,
+      options.providerName,
+      models,
+    );
+
+    const entitiesJsPath = await this.runner.writeConfigFile(
+      "entities.js",
+      entitiesJs,
+      options.rootDir,
+    );
+
+    const config: Record<string, any> = {
+      schema: entitiesJsPath,
+      out: `./migrations/${options.providerName}`,
+      dialect: options.dialect,
+      dbCredentials: {
+        url: options.providerUrl,
+      },
+    };
+
+    if (options.providerName === "pglite") {
+      config.driver = "pglite";
+    }
+
+    const drizzleConfigJs = "export default " + JSON.stringify(config, null, 2);
+
+    return await this.runner.writeConfigFile(
+      "drizzle.config.js",
+      drizzleConfigJs,
+      options.rootDir,
+    );
+  }
+
+  /**
+   * Get DrizzleKitProvider from Alepha instance
+   */
+  protected getKitFromAlepha(alepha: Alepha): any {
+    // biome-ignore lint/complexity/useLiteralKeys: private key
+    return alepha["registry"]
+      .values()
+      .find((it: any) => it.instance.constructor.name === "DrizzleKitProvider")
+      ?.instance;
+  }
+
+  public async loadAlephaFromServerEntryFile(
+    rootDir?: string,
+    explicitEntry?: string,
+  ): Promise<{
+    alepha: Alepha;
+    entry: string;
+  }> {
+    process.env.ALEPHA_SKIP_START = "true";
+
+    const entry = await boot.getServerEntry(rootDir, explicitEntry);
+    const mod = await tsImport(entry, {
+      parentURL: import.meta.url,
+    });
+
+    this.log.debug(`Load entry: ${entry}`);
+
+    // check if alepha is correctly exported
+    if (mod.default instanceof Alepha) {
+      return {
+        alepha: mod.default,
+        entry,
+      };
+    }
+
+    // else, try with global variable
+    const g: any = global;
+    if (g.__alepha) {
+      return {
+        alepha: g.__alepha,
+        entry,
+      };
+    }
+
+    throw new AlephaError(
+      `Could not find Alepha instance in entry file: ${entry}`,
+    );
+  }
+
+  protected generateEntitiesJs(
+    entry: string,
+    provider: string,
+    models: string[] = [],
+  ) {
+    return `
+import "${entry}";
+import { DrizzleKitProvider, Repository } from "@alepha/postgres";
+
+const alepha = globalThis.__alepha;
+const kit = alepha.inject(DrizzleKitProvider);
+const provider = alepha.services(Repository).find((it) => it.provider.name === "${provider}").provider;
+const models = kit.getModels(provider);
+
+${models.map((it: string) => `export const ${it} = models["${it}"];`).join("\n")}
+
+`.trim();
+  }
+}

package/src/commands/VerifyCommands.ts

@@ -0,0 +1,48 @@
+import { $command } from "@alepha/command";
+import { $inject } from "@alepha/core";
+import { ProcessRunner } from "../services/ProcessRunner.ts";
+
+export class VerifyCommands {
+  runner = $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");
+
+      // run only if migrations dir is present ?
+      //await run("alepha db:check-migrations");
+
+      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.runner.exec("tsc --noEmit");
+    },
+  });
+}