@zerotal/core 1.0.0

package/src/command/builtin/MakeObserverCommand.ts

@@ -0,0 +1,78 @@
+/**
+ * The `make:observer` command, which scaffolds a model observer class.
+ */
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt make:observer <name>` — scaffolds a new model observer class under
+ * `app/observers/` (pass `--model`/`-m` to target a specific model).
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeObserverCommand extends Command {
+  static commandName = "make:observer";
+  static description = "Create a new model observer class";
+  static needsApp = false;
+
+  static args = [
+    { name: "name", required: true, description: "Observer name (e.g. UserObserver)" },
+  ];
+
+  static flags = [
+    {
+      name: "model",
+      short: "m",
+      type: "string" as const,
+      description: "Model the observer is for (e.g. User)",
+      default: "",
+    },
+  ];
+
+  async run(): Promise<void> {
+    const name = this.args["name"]!;
+    const model = (this.flags["model"] as string) || name.replace(/Observer$/, "");
+    const path = `app/observers/${name}.ts`;
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    await Bun.write(path, _stub(name, model));
+    this.info(`Created: ${path}`);
+    this.line("");
+    this.line(`Register it in a ServiceProvider:`);
+    this.dim(`  ${model}.observe(${name});`);
+  }
+}
+
+function _stub(name: string, model: string): string {
+  return `import type { ModelObserver } from '@zerotal/orm';
+
+export class ${name} implements ModelObserver {
+  creating(${model.toLowerCase()}: Record<string, unknown>): void {
+    //
+  }
+
+  created(${model.toLowerCase()}: Record<string, unknown>): void {
+    //
+  }
+
+  updating(${model.toLowerCase()}: Record<string, unknown>): void {
+    //
+  }
+
+  updated(${model.toLowerCase()}: Record<string, unknown>): void {
+    //
+  }
+
+  deleting(${model.toLowerCase()}: Record<string, unknown>): void {
+    //
+  }
+
+  deleted(${model.toLowerCase()}: Record<string, unknown>): void {
+    //
+  }
+}
+`;
+}

package/src/command/builtin/MakePackageCommand.ts

@@ -0,0 +1,45 @@
+/**
+ * The `make:package` command, which scaffolds a conformant `@zerotal/<name>`
+ * workspace package on disk.
+ */
+import { Command } from "../Command.ts";
+import { scaffoldPackage, packageNames } from "../../build/PackageScaffold.ts";
+
+/**
+ * `bun zt make:package <name>` — scaffolds a conformant `@zerotal/<name>`
+ * workspace package on disk.
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakePackageCommand extends Command {
+  static commandName = "make:package";
+  static description = "Scaffold a conformant @zerotal/<name> package";
+  static needsApp = false;
+  static args = [
+    { name: "name", required: true },
+    { name: "baseDir", required: false, default: "./packages" },
+  ];
+  static flags = [];
+
+  async run(): Promise<void> {
+    const rawName = this.args["name"]!;
+    const baseDir = (this.args["baseDir"] as string | undefined) || "./packages";
+    const { token } = packageNames(rawName);
+    if (!token) {
+      this.error(`Invalid package name: "${rawName}"`);
+      return;
+    }
+    const packageDir = `${baseDir}/${token}`;
+    if (await Bun.file(`${packageDir}/package.json`).exists()) {
+      this.error(`Package already exists: ${packageDir}`);
+      return;
+    }
+    const files = scaffoldPackage(rawName);
+    for (const [relativePath, content] of files)
+      await Bun.write(`${packageDir}/${relativePath}`, content);
+    this.section(`Created @zerotal/${token}`);
+    for (const relativePath of files.keys()) this.info(`  ${packageDir}/${relativePath}`);
+    this.newLine();
+    this.line(`Next: add it to your app's providers, then run 'bun zerotal lint:packages'.`);
+  }
+}

package/src/command/builtin/MakePolicyCommand.ts

@@ -0,0 +1,66 @@
+/**
+ * The `make:policy` command and the authorization-policy source stub it writes.
+ */
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt make:policy <name>` — scaffolds a new authorization policy class
+ * under `app/policies/` (pass `--model`/`-m` to bind it to a model).
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakePolicyCommand extends Command {
+  static commandName = "make:policy";
+  static description = "Create a new authorization policy class";
+  static needsApp = false;
+  static args = [{ name: "name", required: true, description: "Policy name (e.g. PostPolicy)" }];
+  static flags = [
+    {
+      name: "model",
+      short: "m",
+      type: "string" as const,
+      description: "The model this policy is for (e.g. Post)",
+      default: "",
+    },
+  ];
+
+  async run(): Promise<void> {
+    const name = this.args["name"]!;
+    const model = (this.flags["model"] as string) || name.replace(/Policy$/, "");
+    const path = `app/policies/${name}.ts`;
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    await Bun.write(path, policyStub(name, model));
+    this.info(`Created: ${path}`);
+  }
+}
+
+/** Source for a new authorization policy class extending `Policy`. */
+export function policyStub(name: string, model: string): string {
+  return `import { Policy } from '@zerotal/auth';
+// import type { ${model} } from '../models/${model}.ts';
+// import type { User } from '../models/User.ts';
+
+export class ${name} extends Policy<unknown> {
+  view(_user: unknown | null, _resource: unknown): boolean {
+    return true;
+  }
+
+  create(_user: unknown): boolean {
+    return true;
+  }
+
+  update(_user: unknown, _resource: unknown): boolean {
+    return true;
+  }
+
+  delete(_user: unknown, _resource: unknown): boolean {
+    return true;
+  }
+}
+`;
+}

package/src/command/builtin/MakeProviderCommand.ts

@@ -0,0 +1,75 @@
+/**
+ * The `make:provider` command, which scaffolds a service provider and (unless
+ * skipped) wires it into `bootstrap/providers.ts`.
+ */
+import { Command } from "../Command.ts";
+import { registerProvider } from "../../build/codemod.ts";
+
+function providerStub(name: string): string {
+  return `import { ServiceProvider } from '@zerotal/core';
+
+export class ${name} extends ServiceProvider {
+  override onRegister(): void {
+    // Bind singletons into the container here.
+    // this.app.container.singleton('my-service', () => new MyService());
+  }
+
+  override async onBooting(): Promise<void> {
+    // Called after all providers are registered.
+    // Safe to resolve other bindings from the container.
+  }
+
+  override async onBooted(): Promise<void> {
+    // Called after all providers have finished booting.
+    // Use for cross-provider wiring (e.g. registering commands, events).
+  }
+}
+`;
+}
+
+/**
+ * `bun zt make:provider <name>` — scaffolds a new service provider class under
+ * `app/providers/` and (unless skipped) wires it into `bootstrap/providers.ts`.
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeProviderCommand extends Command {
+  static commandName = "make:provider";
+  static description = "Create a new service provider class";
+  static needsApp = false;
+  static args = [{ name: "name", required: true }];
+  static flags = [
+    {
+      name: "no-register",
+      type: "boolean" as const,
+      description: "Skip registering in bootstrap/providers.ts",
+      default: false,
+    },
+  ];
+
+  async run(): Promise<void> {
+    const name = this.args["name"]!;
+    const className = name.endsWith("Provider") ? name : `${name}Provider`;
+    const path = `app/providers/${className}.ts`;
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    await Bun.write(path, providerStub(className));
+    this.info(`Created: ${path}`);
+
+    // Codemod: wire the new provider into bootstrap/providers.ts.
+    if (this.flags["no-register"] !== true) {
+      const result = await registerProvider({
+        className,
+        importPath: `../app/providers/${className}.ts`,
+      });
+      if (result === "added") this.info("Registered in bootstrap/providers.ts");
+      if (result === "exists") this.info("Already registered in bootstrap/providers.ts");
+      if (result === "missing")
+        this.warn("bootstrap/providers.ts not found — add the provider manually.");
+    }
+  }
+}

package/src/command/builtin/MakeRequestCommand.ts

@@ -0,0 +1,47 @@
+/**
+ * The `make:request` command, which scaffolds a FormRequest validation class.
+ */
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt make:request <name>` — scaffolds a new FormRequest validation class
+ * under `app/requests/`.
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeRequestCommand extends Command {
+  static commandName = "make:request";
+  static description = "Create a new FormRequest 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/requests/${name}.ts`;
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+    await Bun.write(path, stub(name));
+    this.info(`Created: ${path}`);
+  }
+}
+
+function stub(name: string): string {
+  return `import { FormRequest } from '@zerotal/validator';
+import type { RuleBuilder }  from '@zerotal/validator';
+import type { FieldRule }    from '@zerotal/validator';
+
+export class ${name} extends FormRequest {
+  rules(r: RuleBuilder): Record<string, FieldRule> {
+    return {
+      // example: title: r.string().min(3).max(255),
+    };
+  }
+}
+`;
+}

package/src/command/builtin/MakeResourceCommand.ts

@@ -0,0 +1,61 @@
+/**
+ * The `make:resource` command, which scaffolds an API resource transformer.
+ */
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt make:resource <name>` — scaffolds a new API resource transformer
+ * class under `app/resources/`.
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeResourceCommand extends Command {
+  static commandName = "make:resource";
+  static description = "Create a new API resource transformer class";
+  static needsApp = false;
+
+  static args = [
+    { name: "name", required: true, description: "Resource name (e.g. UserResource)" },
+  ];
+
+  async run(): Promise<void> {
+    const name = this.args["name"]!;
+    const path = `app/resources/${name}.ts`;
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    await Bun.write(path, _stub(name));
+    this.info(`Created: ${path}`);
+  }
+}
+
+function _stub(name: string): string {
+  const model = name.replace(/Resource$/, "");
+  const snake = model.replace(/([A-Z])/g, (char, index) => (index ? "-" : "") + char.toLowerCase());
+  return `import { Resource, ResourceCollection } from '@zerotal/core';
+import type { PaginatedData } from '@zerotal/core';
+
+export class ${name} extends Resource<${model}> {
+  toArray(): Record<string, unknown> {
+    return {
+      id:         this.resource.id,
+      // Add fields here — omit sensitive ones like 'password'
+      created_at: this.resource.createdAt,
+    };
+  }
+}
+
+// ── Usage in controllers ────────────────────────────────────────────────────
+
+// Single model:
+//   ctx.json(new ${name}(model).toJson());            // { data: { ... } }
+//   ctx.response = new ${name}(model).toResponse(201);
+
+// Paginated list (ResourceCollection adds { data, meta, links } automatically):
+//   const paginated = await ${model}.query().paginate(15, page);
+//   ctx.json(ResourceCollection.of(${name}, paginated, '/api/${snake}'));
+`;
+}

package/src/command/builtin/MakeTestCommand.ts

@@ -0,0 +1,120 @@
+/**
+ * The `make:test` command and the test stubs it writes.
+ */
+import { Command } from "../Command.ts";
+import { pluralize } from "../../support/str.ts";
+
+/** A feature test: boots the app and drives it over real HTTP. */
+export function featureTestStub(name: string): string {
+  const subject = name.replace(/Test$/, "");
+  // Resource routes and tables are plural, so the stub is a starting point you
+  // edit rather than one you have to rewrite.
+  const resource = pluralize(subject.toLowerCase());
+  return `import { describe, it, beforeAll, afterAll } from 'bun:test';
+import { migrateDatabase, refreshDatabase, assertDatabaseHas } from '@zerotal/testing';
+import type { TestApp } from '@zerotal/testing';
+import { createApp } from '../helpers.ts';
+
+let app: TestApp;
+
+beforeAll(async () => {
+  app = await createApp();
+  await migrateDatabase();
+});
+
+afterAll(() => app.close());
+
+describe('${subject}', () => {
+  // Each test runs in a transaction that rolls back, so they start from the
+  // same clean database and can be read in any order.
+  refreshDatabase();
+
+  it('lists ${resource}', async () => {
+    const res = await app.get('/${resource}');
+
+    res.assertOk();
+  });
+
+  it('rejects an invalid payload', async () => {
+    const res = await app.asJson().post('/${resource}', {});
+
+    res.assertUnprocessable();
+    res.assertInvalid();
+  });
+
+  it('creates a record', async () => {
+    const res = await app.asJson().post('/${resource}', { name: 'Example' });
+
+    res.assertCreated();
+    await assertDatabaseHas('${resource}', { name: 'Example' });
+  });
+});
+`;
+}
+
+/** A unit test: no server, no database, just the thing under test. */
+export function unitTestStub(name: string): string {
+  const subject = name.replace(/Test$/, "");
+  return `import { describe, it, expect } from 'bun:test';
+
+describe('${subject}', () => {
+  it('does the thing it exists to do', () => {
+    expect(true).toBe(true);
+  });
+});
+`;
+}
+
+function testPath(name: string, unit: boolean): string {
+  const file = name.endsWith("Test") ? name : `${name}Test`;
+  return `tests/${unit ? "unit" : "feature"}/${file}.ts`;
+}
+
+/**
+ * `bun zt make:test <name>` — scaffolds a test file under `tests/feature/`
+ * (or `tests/unit/` with `--unit`).
+ *
+ * The feature stub boots the app through `tests/helpers.ts`, the file the
+ * templates scaffold, so a generated test runs against the same configured
+ * application as every other test in the suite rather than building its own.
+ *
+ * @category Scaffolding (make:*)
+ */
+export class MakeTestCommand extends Command {
+  static commandName = "make:test";
+  static description = "Create a new test file";
+  static needsApp = false;
+
+  static get args() {
+    return [{ name: "name", required: true, description: "Test name (e.g. PostTest)" }];
+  }
+
+  static get flags() {
+    return [
+      {
+        name: "unit",
+        type: "boolean" as const,
+        description: "Create a unit test (no app, no database) instead of a feature test",
+        default: false,
+      },
+    ];
+  }
+
+  async run(): Promise<void> {
+    const name = this.args["name"]!;
+    const unit = this.flags["unit"] === true;
+    const path = testPath(name, unit);
+
+    if (await Bun.file(path).exists()) {
+      this.error(`File already exists: ${path}`);
+      return;
+    }
+
+    // Bun.write() creates any missing parent directories, so no mkdir is needed.
+    await Bun.write(path, unit ? unitTestStub(name) : featureTestStub(name));
+    this.info(`Created: ${path}`);
+    if (!unit) {
+      this.dim("Feature tests boot the app through tests/helpers.ts — create it if you have not.");
+    }
+  }
+}

package/src/command/builtin/ReloadCommand.ts

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+import { Command } from "../Command.ts";
+
+/**
+ * `bun zt reload` — hot-reloads routes in the running server.
+ *
+ * Sends SIGUSR2 to the running Zerotal server, which triggers a zero-downtime
+ * route hot-swap via `Bun.serve().reload()`. In-flight requests are not
+ * dropped — they finish on the old route table while new requests immediately
+ * use the updated routes.
+ *
+ * Requires: a server started with `bun zt serve` (writes .zerotal/server.pid).
+ *
+ * Platform note: SIGUSR2 is a Unix/macOS signal. On Windows, use WSL or send
+ * the signal via another mechanism.
+ *
+ * @category Serving
+ */
+export class ReloadCommand extends Command {
+  static commandName = "reload";
+  static description = "Hot-reload routes in the running server (sends SIGUSR2)";
+  static needsApp = false;
+  static args = [];
+  static flags = [];
+
+  async run(): Promise<void> {
+    const pidFile = join(process.cwd(), ".zerotal", "server.pid");
+
+    let rawPid: string;
+    try {
+      rawPid = await Bun.file(pidFile).text();
+    } catch {
+      this.error("No .zerotal/server.pid found. Is the server running?");
+      process.exit(1);
+    }
+
+    const pid = parseInt(rawPid.trim(), 10);
+    if (!pid || isNaN(pid)) {
+      this.error(`PID file is invalid: "${rawPid.trim()}"`);
+      process.exit(1);
+    }
+
+    try {
+      process.kill(pid, "SIGUSR2");
+      this.info(`↺  SIGUSR2 sent to PID ${pid} — routes are reloading.`);
+    } catch (error) {
+      this.error(`Failed to signal process ${pid}: ${(error as Error).message}`);
+      this.dim("Is the server still running? Check with: bun zerotal.ts status");
+      process.exit(1);
+    }
+  }
+}