@zerotal/core 1.0.0

package/src/command/builtin/CssBuildCommand.ts

@@ -0,0 +1,71 @@
+import { Command } from "../Command.ts";
+import { buildCssBundle } from "../../dev/CssPlugins.ts";
+
+/**
+ * `bun zt css:build` — builds the Tailwind CSS bundle for production.
+ *
+ * Used by Pulse and View apps (Inertia uses `inertia:build` instead).
+ *
+ * Input:  resources/css/app.css
+ * Output: public/css/app.css
+ *
+ * @category Build & assets
+ */
+export class CssBuildCommand extends Command {
+  static commandName = "css:build";
+  static description = "Build the Tailwind CSS bundle for production";
+  static needsApp = false;
+
+  static flags = [
+    {
+      name: "input",
+      short: "i",
+      type: "string" as const,
+      description: "Path to the CSS entry point",
+      default: "resources/css/app.css",
+    },
+    {
+      name: "output",
+      short: "o",
+      type: "string" as const,
+      description: "Output directory",
+      default: "public/css",
+    },
+    {
+      name: "minify",
+      short: "m",
+      type: "boolean" as const,
+      description: "Minify the output",
+      default: true,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const cwd = process.cwd();
+    const input = this.flags["input"] as string;
+    const output = this.flags["output"] as string;
+    const minify = this.flags["minify"] as boolean;
+
+    const absoluteInput = input.startsWith("/") ? input : `${cwd}/${input}`;
+    const absoluteOutput = output.startsWith("/") ? output : `${cwd}/${output}`;
+
+    const cssExists = await Bun.file(absoluteInput).exists();
+    if (!cssExists) {
+      this.error(`CSS entry point not found: ${input}`);
+      return;
+    }
+
+    this.info(`Building CSS: ${input} → ${output}/`);
+
+    const result = await buildCssBundle(absoluteInput, absoluteOutput, minify);
+
+    if (!result.success) {
+      for (const log of result.logs) {
+        this.error(String(log));
+      }
+      throw new Error("CSS build failed.");
+    }
+
+    this.info("CSS build complete.");
+  }
+}

package/src/command/builtin/KeyGenerateCommand.ts

@@ -0,0 +1,58 @@
+/**
+ * The `key:generate` command and the helpers it uses to mint an APP_KEY and
+ * write it into the project's `.env` file.
+ */
+import { Command } from "../Command.ts";
+
+/** Generate a random 32-byte base64 application key. */
+export function generateKey(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Buffer.from(bytes).toString("base64");
+}
+
+/** Return true if the given .env content already has an APP_KEY line. */
+function hasAppKey(content: string): boolean {
+  return content.includes("APP_KEY=");
+}
+
+/** Insert or replace the APP_KEY line in .env file content. */
+export function updateEnvContent(content: string, key: string): string {
+  return hasAppKey(content)
+    ? content.replace(/^APP_KEY=.*$/m, `APP_KEY=${key}`)
+    : content + `\nAPP_KEY=${key}\n`;
+}
+
+/**
+ * `bun zt key:generate` — generates a new random APP_KEY and writes it to the
+ * project's `.env` file.
+ *
+ * @category App setup
+ */
+export class KeyGenerateCommand extends Command {
+  static commandName = "key:generate";
+  static description = "Generate a new APP_KEY and write it to .env";
+  static needsApp = false;
+
+  static get args() {
+    return [];
+  }
+  static get flags() {
+    return [];
+  }
+
+  run(): Promise<void> {
+    const key = generateKey();
+    const envPath = ".env";
+
+    return Bun.file(envPath)
+      .text()
+      .catch(() => "")
+      .then((content) => {
+        return Bun.write(envPath, updateEnvContent(content, key)).then(() => {
+          this.info("APP_KEY generated and written to .env");
+          this.dim(`  APP_KEY=${key}`);
+        });
+      });
+  }
+}

package/src/command/builtin/LintPackagesCommand.ts

@@ -0,0 +1,72 @@
+/**
+ * The `lint:packages` command, which checks every workspace package against the
+ * documented conventions and prints a conformance report.
+ */
+import { Command } from "../Command.ts";
+import { lintPackages, countViolations, type Severity } from "../../build/PackageLinter.ts";
+
+const SEVERITY_COLOR: Record<Severity, string> = {
+  high: "\x1b[31m",
+  medium: "\x1b[33m",
+  low: "\x1b[2m",
+};
+const RESET = "\x1b[0m";
+
+/**
+ * `bun zt lint:packages` — checks every workspace package under a directory
+ * against the documented framework conventions and prints a conformance report.
+ *
+ * @category Diagnostics
+ */
+export class LintPackagesCommand extends Command {
+  static commandName = "lint:packages";
+  static description = "Check every package against the documented conventions";
+  static needsApp = false;
+  static args = [{ name: "dir", required: false, default: "./packages" }];
+  static flags = [
+    {
+      name: "quiet",
+      short: "q",
+      type: "boolean" as const,
+      description: "Only print the summary",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const dir = (this.args["dir"] as string | undefined) || "./packages";
+    const quiet = this.flags["quiet"] === true;
+    const reports = await lintPackages(dir);
+    if (reports.length === 0) {
+      this.error(`No packages found under ${dir}`);
+      throw new Error(`lint:packages: no packages found under ${dir}`);
+    }
+    const total = countViolations(reports);
+    const clean = reports.filter((report) => report.violations.length === 0).length;
+    if (!quiet) {
+      this.section(`Package conformance — ${reports.length} packages`);
+      for (const report of reports) {
+        if (report.violations.length === 0) {
+          this.info(`  ✓ ${report.package}`);
+          continue;
+        }
+        this.write(`  \x1b[31m✗\x1b[0m ${report.package}\n`);
+        for (const violation of report.violations) {
+          const color = SEVERITY_COLOR[violation.severity];
+          this.write(
+            `      ${color}${violation.severity.padEnd(6)}${RESET} ${violation.rule.padEnd(22)} ${violation.message}\n`,
+          );
+        }
+      }
+      this.newLine();
+    }
+    if (total === 0) {
+      this.info(`✓ All ${reports.length} packages conform.`);
+      return;
+    }
+    this.error(
+      `✖ ${total} violation${total === 1 ? "" : "s"} across ${reports.length - clean} package${reports.length - clean === 1 ? "" : "s"} (${clean} clean).`,
+    );
+    throw new Error(`lint:packages: ${total} violation(s)`);
+  }
+}

package/src/command/builtin/MakeCommandCommand.ts

@@ -0,0 +1,85 @@
+/**
+ * The `make:command` command and the CLI-command source stub it writes.
+ */
+import { Command } from "../Command.ts";
+
+/** Convert a name to kebab-case (e.g. `SendDailyReport` → `send-daily-report`). */
+export function toKebab(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[_\s]+/g, "-")
+    .replace(/-+/g, "-")
+    .toLowerCase();
+}
+
+/** Source for a new CLI command class extending `Command`. */
+export function commandStub(name: string): string {
+  return `import { Command } from '@zerotal/core';
+import type { ArgDef, FlagDef } from '@zerotal/core';
+
+export class ${name} extends Command {
+  static commandName = '${toKebab(name)}';
+  static description = 'Describe what this command does';
+  static needsApp    = true;
+
+  static args: ArgDef[] = [
+    // { name: 'target', description: 'The target', required: true },
+  ];
+
+  static flags: FlagDef[] = [
+    // { name: 'dry-run', short: 'd', type: 'boolean' as const,
+    //   description: 'Preview without making changes', default: false },
+  ];
+
+  async run(): Promise<void> {
+    this.section('${name}');
+    // your implementation here
+    this.info('Done.');
+  }
+}
+`;
+}
+
+function commandPath(name: string): string {
+  return `app/commands/${name}.ts`;
+}
+
+/**
+ * `bun zt make:command <name>` — scaffolds a new CLI command class (extending
+ * {@link Command}) under `app/commands/`.
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeCommandCommand extends Command {
+  static commandName = "make:command";
+  static description = "Create a new CLI command class";
+  static needsApp = false;
+
+  static get args() {
+    return [
+      { name: "name", required: true, description: "Command class name (e.g. SendDailyReport)" },
+    ];
+  }
+
+  static get flags() {
+    return [];
+  }
+
+  run(): Promise<void> {
+    const name = this.args["name"]!;
+    const path = commandPath(name);
+
+    return Bun.file(path)
+      .exists()
+      .then((exists) => {
+        if (exists) {
+          this.error(`File already exists: ${path}`);
+          return;
+        }
+        // Bun.write() creates any missing parent directories, so no mkdir is needed.
+        return Bun.write(path, commandStub(name)).then(() => {
+          this.info(`Created: ${path}`);
+        });
+      });
+  }
+}

package/src/command/builtin/MakeControllerCommand.ts

@@ -0,0 +1,95 @@
+/**
+ * The `make:controller` command and the controller source stubs it writes.
+ */
+import { Command } from "../Command.ts";
+
+/** Source for a minimal controller with a single `index` action. */
+export function basicStub(name: string): string {
+  return `import type { HttpContext } from '@zerotal/core';
+
+export class ${name} {
+  async index(ctx: HttpContext): Promise<void> {
+    ctx.response = Response.json({ message: 'ok' });
+  }
+}
+`;
+}
+
+/** Source for a resourceful controller with full CRUD action stubs. */
+export function resourceStub(name: string): string {
+  return `import type { HttpContext } from '@zerotal/core';
+
+export class ${name} {
+  async index(ctx: HttpContext): Promise<void> {
+    ctx.response = Response.json([]);
+  }
+
+  async show(ctx: HttpContext): Promise<void> {
+    const { id } = ctx.params;
+    ctx.response = Response.json({ id });
+  }
+
+  async store(ctx: HttpContext): Promise<void> {
+    const body = await ctx.request.json();
+    ctx.response = Response.json(body, { status: 201 });
+  }
+
+  async update(ctx: HttpContext): Promise<void> {
+    const body = await ctx.request.json();
+    ctx.response = Response.json(body);
+  }
+
+  async destroy(ctx: HttpContext): Promise<void> {
+    ctx.response = new Response(null, { status: 204 });
+  }
+}
+`;
+}
+
+/**
+ * `bun zt make:controller <name>` — scaffolds a new controller class under
+ * `app/controllers/` (pass `--resource` for a full CRUD controller).
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeControllerCommand extends Command {
+  static commandName = "make:controller";
+  static description = "Create a new controller class";
+  static needsApp = false;
+
+  static get args() {
+    return [
+      { name: "name", required: true, description: "Controller class name (e.g. UserController)" },
+    ];
+  }
+
+  static get flags() {
+    return [
+      {
+        name: "resource",
+        type: "boolean" as const,
+        description: "Include CRUD action stubs",
+        default: false,
+      },
+    ];
+  }
+
+  run(): Promise<void> {
+    const name = this.args["name"]!;
+    const resource = this.flags["resource"] as boolean;
+    const path = `app/controllers/${name}.ts`;
+
+    return Bun.file(path)
+      .exists()
+      .then((exists) => {
+        if (exists) {
+          this.error(`File already exists: ${path}`);
+          return;
+        }
+        // Bun.write() creates any missing parent directories, so no mkdir is needed.
+        return Bun.write(path, resource ? resourceStub(name) : basicStub(name)).then(() => {
+          this.info(`Created: ${path}`);
+        });
+      });
+  }
+}

package/src/command/builtin/MakeEventCommand.ts

@@ -0,0 +1,85 @@
+/**
+ * The `make:event` command and the event source stubs it writes (plain and
+ * broadcastable).
+ */
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt make:event <name>` — scaffolds a new event class under `app/events/`
+ * (pass `--broadcast`/`-b` for a broadcastable event extending `BroadcastingEvent`).
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeEventCommand extends Command {
+  static commandName = "make:event";
+  static description = "Create a new event class";
+  static needsApp = false;
+  static override args = [{ name: "name", required: true, default: "" }];
+  static override flags = [
+    {
+      name: "broadcast",
+      short: "b",
+      type: "boolean" as const,
+      description: "Generate a broadcastable event (extends BroadcastingEvent)",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const name = this.args["name"];
+    if (!name) {
+      this.error("Name is required.");
+      return;
+    }
+    const path = `app/events/${name}.ts`;
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+    const broadcast = this.flags["broadcast"] as boolean;
+    await Bun.write(path, broadcast ? broadcastEventStub(name) : plainEventStub(name));
+    this.info(`Created: ${path}`);
+  }
+}
+
+function plainEventStub(name: string): string {
+  return `/**\n * ${name} event.\n */\nexport class ${name} {\n  constructor(\n    // public readonly userId: number,\n  ) {}\n}\n`;
+}
+
+/** Source for a broadcastable event that extends `BroadcastingEvent`. */
+export function broadcastEventStub(name: string): string {
+  return `import { BroadcastingEvent, privateChannel } from "@zerotal/broadcasting";
+
+/**
+ * ${name} - a broadcastable event.
+ *
+ * Dispatch it (broadcasts + runs any listeners):
+ *   ${name}.dispatch(order);
+ *
+ * Or broadcast to everyone but the current user:
+ *   broadcast(new ${name}(order)).toOthers();
+ */
+export class ${name} extends BroadcastingEvent {
+  constructor(
+    // public readonly order: Order,
+  ) {
+    super();
+  }
+
+  /** The channel(s) this event broadcasts on. Use [param] placeholders in channel auth rules. */
+  broadcastOn() {
+    return privateChannel("channel-name");
+  }
+
+  /** Optional: the wire payload (defaults to this event's own public properties). */
+  broadcastWith() {
+    return {};
+  }
+
+  /** Optional: only broadcast when this returns true. */
+  // broadcastWhen() {
+  //   return true;
+  // }
+}
+`;
+}

package/src/command/builtin/MakeJobCommand.ts

@@ -0,0 +1,53 @@
+/**
+ * The `make:job` command, which scaffolds a queue job class.
+ */
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt make:job <name>` — scaffolds a new queue job class under `app/jobs/`.
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeJobCommand extends Command {
+  static commandName = "make:job";
+  static description = "Create a new queue job class";
+  static needsApp = false;
+  static override args = [{ name: "name", required: true, default: "" }];
+
+  async run(): Promise<void> {
+    const name = this.args["name"];
+    if (!name) {
+      this.error("Name is required.");
+      return;
+    }
+    const path = `app/jobs/${name}.ts`;
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+    await Bun.write(
+      path,
+      `import { Job, JobRegistry } from '@zerotal/queue';
+
+export class ${name} extends Job {
+  readonly queue = 'default';
+
+  constructor(
+    // public readonly id: number,
+  ) { super(); }
+
+  payload(): Record<string, unknown> {
+    return {};
+  }
+
+  async handle(): Promise<void> {
+    // Implement the job logic here
+  }
+}
+
+JobRegistry.register(${name} as never);
+`,
+    );
+    this.info(`Created: ${path}`);
+  }
+}

package/src/command/builtin/MakeListenerCommand.ts

@@ -0,0 +1,35 @@
+/**
+ * The `make:listener` command, which scaffolds an event listener class.
+ */
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt make:listener <name>` — scaffolds a new event listener class under
+ * `app/listeners/`.
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeListenerCommand extends Command {
+  static commandName = "make:listener";
+  static description = "Create a new event listener class";
+  static needsApp = false;
+  static override args = [{ name: "name", required: true, default: "" }];
+
+  async run(): Promise<void> {
+    const name = this.args["name"];
+    if (!name) {
+      this.error("Name is required.");
+      return;
+    }
+    const path = `app/listeners/${name}.ts`;
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+    await Bun.write(
+      path,
+      `export class ${name} {\n  async handle(event: unknown): Promise<void> {\n    // Handle the event here\n    void event;\n  }\n}\n`,
+    );
+    this.info(`Created: ${path}`);
+  }
+}

package/src/command/builtin/MakeMiddlewareCommand.ts

@@ -0,0 +1,63 @@
+/**
+ * The `make:middleware` command and the middleware source stub it writes.
+ */
+import { Command } from "../Command.ts";
+
+/** Source for a pass-through middleware class implementing `Pipe<HttpContext>`. */
+export function middlewareStub(name: string): string {
+  return `import type { HttpContext, Pipe, NextFn } from '@zerotal/core';
+
+export class ${name} implements Pipe<HttpContext> {
+  async handle(ctx: HttpContext, next: NextFn): Promise<Response | void> {
+    // Continue down the pipeline:
+    return next();
+    // ...or short-circuit by returning a Response instead of calling next():
+    // return Response.json({ message: 'Forbidden' }, { status: 403 });
+  }
+}
+`;
+}
+
+function middlewarePath(name: string): string {
+  return `app/middleware/${name}.ts`;
+}
+
+/**
+ * `bun zt make:middleware <name>` — scaffolds a new middleware class
+ * (implementing `Pipe<HttpContext>`) under `app/middleware/`.
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeMiddlewareCommand extends Command {
+  static commandName = "make:middleware";
+  static description = "Create a new middleware class";
+  static needsApp = false;
+
+  static get args() {
+    return [
+      { name: "name", required: true, description: "Middleware class name (e.g. AuthMiddleware)" },
+    ];
+  }
+
+  static get flags() {
+    return [];
+  }
+
+  run(): Promise<void> {
+    const name = this.args["name"]!;
+    const path = middlewarePath(name);
+
+    return Bun.file(path)
+      .exists()
+      .then((exists) => {
+        if (exists) {
+          this.error(`File already exists: ${path}`);
+          return;
+        }
+        // Bun.write() creates any missing parent directories, so no mkdir is needed.
+        return Bun.write(path, middlewareStub(name)).then(() => {
+          this.info(`Created: ${path}`);
+        });
+      });
+  }
+}

package/src/command/builtin/MakeNotificationCommand.ts

@@ -0,0 +1,48 @@
+/**
+ * The `make:notification` command and the notification source stub it writes.
+ */
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt make:notification <name>` — scaffolds a new notification class under
+ * `app/notifications/`.
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeNotificationCommand extends Command {
+  static commandName = "make:notification";
+  static description = "Create a new notification class";
+  static needsApp = false;
+  static args = [
+    { name: "name", required: true, description: "Notification name (e.g. OrderShipped)" },
+  ];
+
+  async run(): Promise<void> {
+    const name = this.args["name"]!;
+    const path = `app/notifications/${name}.ts`;
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    await Bun.write(path, notificationStub(name));
+    this.info(`Created: ${path}`);
+  }
+}
+
+/** Source for a new notification class extending `Notification`. */
+export function notificationStub(name: string): string {
+  return `import { Notification } from '@zerotal/notifications';
+
+export class ${name} extends Notification {
+  channels(): string[] {
+    return ['database'];
+  }
+
+  toDatabase(): Record<string, unknown> {
+    return {};
+  }
+}
+`;
+}