alepha 0.23.0 → 0.24.0

package/src/logger/__tests__/CliFormatterProvider.spec.ts

@@ -0,0 +1,76 @@
+import { Alepha, AlephaError } from "alepha";
+import { describe, it } from "vitest";
+import {
+  $logger,
+  CliFormatterProvider,
+  LogDestinationProvider,
+  LogFormatterProvider,
+  MemoryDestinationProvider,
+} from "../index.ts";
+
+describe("CliFormatterProvider", () => {
+  class App {
+    log = $logger();
+  }
+
+  const createApp = () =>
+    Alepha.create({
+      env: {
+        LOG_LEVEL: "trace",
+        NO_COLOR: "true",
+      },
+    })
+      .with({
+        provide: LogFormatterProvider,
+        use: CliFormatterProvider,
+      })
+      .with({
+        provide: LogDestinationProvider,
+        use: MemoryDestinationProvider,
+      });
+
+  it("renders time, level initial and message (no module/service)", ({
+    expect,
+  }) => {
+    const alepha = createApp();
+    const app = alepha.inject(App);
+
+    app.log.info("Starting 'alepha lint' ...");
+
+    const output = alepha.inject(MemoryDestinationProvider);
+    const fmt = alepha.inject(CliFormatterProvider);
+
+    expect(output.logs[0].formatted).toBe(
+      `${(fmt as any).formatClockTime(output.logs[0].timestamp)} I Starting 'alepha lint' ...`,
+    );
+  });
+
+  it("appends structured data as json", ({ expect }) => {
+    const alepha = createApp();
+    const app = alepha.inject(App);
+
+    app.log.info("Finished", { json: { key: "value" }, count: 2 });
+
+    const output = alepha.inject(MemoryDestinationProvider);
+    const fmt = alepha.inject(CliFormatterProvider);
+
+    expect(output.logs[0].formatted).toBe(
+      `${(fmt as any).formatClockTime(output.logs[0].timestamp)} I Finished {"json":{"key":"value"},"count":2}`,
+    );
+  });
+
+  it("uses the level initial for warnings and errors", ({ expect }) => {
+    const alepha = createApp();
+    const app = alepha.inject(App);
+
+    app.log.warn("a warning");
+    const error = new AlephaError("boom");
+    app.log.error("failed", new Error("wrapper", { cause: error }));
+
+    const output = alepha.inject(MemoryDestinationProvider);
+
+    expect(output.logs[0].formatted).toContain(" W a warning");
+    expect(output.logs[1].formatted).toContain(" E failed");
+    expect(output.logs[1].formatted).toContain("Caused by: AlephaError: boom");
+  });
+});

package/src/logger/__tests__/Logger.spec.ts

@@ -347,4 +347,53 @@ describe("Logger", () => {
       expect(logger.activeFormatter).toBeInstanceOf(PrettyFormatterProvider);
     });
   });
+
+  describe("isLevelEnabled", () => {
+    const at = (level: string) => {
+      const alepha = Alepha.create().with({
+        provide: LogDestinationProvider,
+        use: MemoryDestinationProvider,
+      });
+      const logger = alepha.inject(Logger, {
+        lifetime: "transient",
+        args: ["TestService", "test.module"],
+      });
+      // Set after inject: the logger module's register defaults the level to
+      // "trace" in test mode, so a pre-inject set would be overwritten.
+      alepha.store.set("alepha.logger.level", level);
+      return { alepha, logger };
+    };
+
+    it("enables a level only when it is at or above the active level", ({
+      expect,
+    }) => {
+      const { logger } = at("info");
+      expect(logger.isLevelEnabled("ERROR")).toBe(true);
+      expect(logger.isLevelEnabled("WARN")).toBe(true);
+      expect(logger.isLevelEnabled("INFO")).toBe(true);
+      expect(logger.isLevelEnabled("DEBUG")).toBe(false);
+      expect(logger.isLevelEnabled("TRACE")).toBe(false);
+    });
+
+    it("enables DEBUG once the active level is debug, but not TRACE", ({
+      expect,
+    }) => {
+      const { logger } = at("debug");
+      expect(logger.isLevelEnabled("DEBUG")).toBe(true);
+      expect(logger.isLevelEnabled("INFO")).toBe(true);
+      expect(logger.isLevelEnabled("TRACE")).toBe(false);
+    });
+
+    it("enables everything at trace and reacts to live state changes", ({
+      expect,
+    }) => {
+      const { alepha, logger } = at("trace");
+      expect(logger.isLevelEnabled("TRACE")).toBe(true);
+      expect(logger.isLevelEnabled("DEBUG")).toBe(true);
+
+      alepha.store.set("alepha.logger.level", "warn");
+      expect(logger.isLevelEnabled("DEBUG")).toBe(false);
+      expect(logger.isLevelEnabled("WARN")).toBe(true);
+    });
+  });
 });

package/src/logger/index.ts

@@ -1,5 +1,6 @@
-import { $module, type Static, t } from "alepha";
+import { $module, type Static, z } from "alepha";
 import { $logger } from "./primitives/$logger.ts";
+import { CliFormatterProvider } from "./providers/CliFormatterProvider.ts";
 import { ConsoleColorProvider } from "./providers/ConsoleColorProvider.ts";
 import { ConsoleDestinationProvider } from "./providers/ConsoleDestinationProvider.ts";
 import { JsonFormatterProvider } from "./providers/JsonFormatterProvider.ts";
@@ -14,6 +15,7 @@ import { Logger } from "./services/Logger.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./primitives/$logger.ts";
+export * from "./providers/CliFormatterProvider.ts";
 export * from "./providers/ConsoleColorProvider.ts";
 export * from "./providers/ConsoleDestinationProvider.ts";
 export * from "./providers/JsonFormatterProvider.ts";
@@ -34,6 +36,7 @@ export * from "./services/Logger.ts";
  * - Global logger access
  * - JSON format
  * - Pretty colored output
+ * - Compact CLI format
  * - Raw text format
  * - Console destination
  * - Memory destination (for devtools)
@@ -52,6 +55,7 @@ export const AlephaLogger = $module({
     JsonFormatterProvider,
     PrettyFormatterProvider,
     RawFormatterProvider,
+    CliFormatterProvider,
   ],
   register: (alepha) => {
     const env = alepha.parseEnv(envSchema);
@@ -107,6 +111,9 @@ export const AlephaLogger = $module({
         if (logFormat === "raw") {
           return RawFormatterProvider;
         }
+        if (logFormat === "cli") {
+          return CliFormatterProvider;
+        }
         return PrettyFormatterProvider;
       }
 
@@ -151,7 +158,7 @@ export const AlephaLogger = $module({
 
 // ---------------------------------------------------------------------------------------------------------------------
 
-const envSchema = t.object({
+const envSchema = z.object({
   /**
    * Enable debug logging for specific modules using the `debug` package convention.
    *
@@ -161,12 +168,12 @@ const envSchema = t.object({
    * DEBUG=alepha:orm:* # Enable debug logging for alepha.orm modules
    * DEBUG=* # Enable debug logging for all modules
    */
-  DEBUG: t.optional(
-    t.text({
+  DEBUG: z
+    .text({
       description:
         "Enable debug logging for specific modules using the debug package convention. Example: DEBUG=alepha:*",
-    }),
-  ),
+    })
+    .optional(),
 
   /**
    * Default log level for the application.
@@ -184,29 +191,29 @@ const envSchema = t.object({
    * LOG_LEVEL=my.module.name:debug,info # Set debug level for my.module.name and info for all other modules
    * LOG_LEVEL=alepha:trace, info # Set trace level for all alepha modules and info for all other modules
    */
-  LOG_LEVEL: t.optional(
-    t.text({
+  LOG_LEVEL: z
+    .text({
       description: `Application log level on startup.
 Levels are: trace, debug, info, warn, error, silent
 Level can be set for a specific module:
 "my.module.name:debug,info" -> Set debug level for my.module.name and info for all other modules
 "alepha:trace,info" -> Set trace level for all alepha modules and info for all other modules`,
       lowercase: true,
-    }),
-  ),
+    })
+    .optional(),
 
   /**
    * Built-in log formats.
    * - "json" - JSON format, useful for structured logging and log aggregation. {@link JsonFormatterProvider}
-   * - "pretty" - Simple text format, human-readable, with colors. {@link PrettyFormatterProvider}
-   * - "raw" - Raw format, no formatting, just the message. {@link RawFormatterProvider}
+   * - "pretty" - Full text format, human-readable, with colors and module/context. {@link PrettyFormatterProvider}
+   * - "cli" - Compact format for CLI sessions: time, level initial, message, json. {@link CliFormatterProvider}
+   * - "raw" - Raw format, no formatting, just the message (best for piping). {@link RawFormatterProvider}
    */
-  LOG_FORMAT: t.optional(
-    t.enum(["json", "pretty", "raw"], {
-      description: "Default log format for the application.",
-      lowercase: true,
-    }),
-  ),
+  LOG_FORMAT: z
+    .enum(["json", "pretty", "raw", "cli"])
+    .meta({ lowercase: true })
+    .describe("Default log format for the application.")
+    .optional(),
 });
 
 // ---------------------------------------------------------------------------------------------------------------------

package/src/logger/providers/CliFormatterProvider.ts

@@ -0,0 +1,75 @@
+import type { LogEntry } from "../schemas/logEntrySchema.ts";
+import { PrettyFormatterProvider } from "./PrettyFormatterProvider.ts";
+
+/**
+ * Compact formatter for CLI output.
+ *
+ * Renders `HH:MM:SS L message {json}` — a short clock time, a single-letter
+ * level colored by severity, the message, and any structured data appended
+ * dim. Deliberately drops the `<module.service>`, app name and context UUID
+ * that {@link PrettyFormatterProvider} prints: in an interactive CLI session
+ * those are noise. Use `pretty` (or `--verbose`) when you need them, `raw`
+ * when you want the bare message for piping, and `json` for aggregation.
+ */
+export class CliFormatterProvider extends PrettyFormatterProvider {
+  public override format(entry: LogEntry): string {
+    const { data, timestamp, level } = entry;
+
+    const isError = data instanceof Error;
+    let details = "";
+
+    if (isError) {
+      details = this.formatError(data);
+    } else if (data) {
+      let error = "";
+      let jsonData = data;
+      if ("error" in data && data.error instanceof Error) {
+        error = this.formatError(data.error);
+        const { error: _, ...rest } = data;
+        jsonData = rest;
+      }
+
+      if (Object.keys(jsonData).length > 0) {
+        try {
+          details = JSON.stringify(jsonData);
+        } catch {
+          details = "[Unserializable Object]";
+        }
+      }
+
+      if (error) {
+        details += `\n${error}`;
+      }
+    }
+
+    let output = "";
+
+    output += this.color.set("GREY_DARK", this.formatClockTime(timestamp));
+    output += " ";
+    output += this.color.set(level, level.charAt(0).toUpperCase());
+
+    if (entry.message) {
+      output += ` ${entry.message}`;
+    }
+
+    if (details) {
+      if (isError) {
+        output += ` \n${details}`;
+      } else {
+        output += ` ${this.color.set("GREY_DARK", details)}`;
+      }
+    }
+
+    return output;
+  }
+
+  /**
+   * Short clock time without milliseconds (HH:MM:SS).
+   */
+  protected formatClockTime(timestamp: number): string {
+    const d = new Date(timestamp);
+    return `${this.pad2(d.getHours())}:${this.pad2(d.getMinutes())}:${this.pad2(
+      d.getSeconds(),
+    )}`;
+  }
+}

package/src/logger/schemas/logEntrySchema.ts

@@ -1,16 +1,16 @@
-import { type Static, t } from "alepha";
+import { type Static, z } from "alepha";
 
-export const logEntrySchema = t.object({
-  level: t.enum(["SILENT", "TRACE", "DEBUG", "INFO", "WARN", "ERROR"]),
-  message: t.text({
+export const logEntrySchema = z.object({
+  level: z.enum(["SILENT", "TRACE", "DEBUG", "INFO", "WARN", "ERROR"]),
+  message: z.text({
     size: "rich",
   }),
-  service: t.text(),
-  module: t.text(),
-  context: t.optional(t.text()),
-  app: t.optional(t.text()),
-  data: t.optional(t.any()),
-  timestamp: t.number(),
+  service: z.text(),
+  module: z.text(),
+  context: z.text().optional(),
+  app: z.text().optional(),
+  data: z.any().optional(),
+  timestamp: z.number(),
 });
 
 export type LogEntry = Static<typeof logEntrySchema>;

package/src/logger/services/Logger.ts

@@ -6,6 +6,7 @@ import {
   type LogLevel,
 } from "alepha";
 import { DateTimeProvider } from "alepha/datetime";
+import { CliFormatterProvider } from "../providers/CliFormatterProvider.ts";
 import { JsonFormatterProvider } from "../providers/JsonFormatterProvider.ts";
 import { LogDestinationProvider } from "../providers/LogDestinationProvider.ts";
 import { LogFormatterProvider } from "../providers/LogFormatterProvider.ts";
@@ -24,6 +25,7 @@ export class Logger implements LoggerInterface {
   protected readonly jsonFormatter = $inject(JsonFormatterProvider);
   protected readonly prettyFormatter = $inject(PrettyFormatterProvider);
   protected readonly rawFormatter = $inject(RawFormatterProvider);
+  protected readonly cliFormatter = $inject(CliFormatterProvider);
   protected readonly destination = $inject(LogDestinationProvider);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
 
@@ -76,6 +78,8 @@ export class Logger implements LoggerInterface {
         return this.prettyFormatter;
       case "raw":
         return this.rawFormatter;
+      case "cli":
+        return this.cliFormatter;
       default:
         return this.defaultFormatter;
     }
@@ -145,6 +149,20 @@ export class Logger implements LoggerInterface {
     throw new AlephaError(`Invalid log level: ${something}`);
   }
 
+  /**
+   * Whether a message at `level` would actually be emitted given the current
+   * active level (read live from state). Mirrors the threshold used by
+   * {@link log}: a level is enabled when it sits at or above the active one.
+   *
+   * @example
+   * // active level = INFO
+   * log.isLevelEnabled("DEBUG"); // false
+   * log.isLevelEnabled("WARN");  // true
+   */
+  public isLevelEnabled(level: LogLevel): boolean {
+    return this.levels[level] <= this.levels[this.level];
+  }
+
   // -------------------------------------------------------------------------------------------------------------------
 
   public error(message: string, data?: unknown): void {

package/src/mcp/__tests__/$prompt.spec.ts

@@ -1,4 +1,4 @@
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { describe, expect, test } from "vitest";
 import {
   $prompt,
@@ -16,8 +16,8 @@ describe("$prompt primitive", () => {
     class Prompts {
       greeting = $prompt({
         description: "Generate a greeting",
-        args: t.object({
-          name: t.text(),
+        args: z.object({
+          name: z.text(),
         }),
         handler: async ({ args }) => [
           { role: "user", content: `Say hello to ${args.name}` },
@@ -63,9 +63,9 @@ describe("$prompt primitive", () => {
     class Prompts {
       review = $prompt({
         description: "Request a code review",
-        args: t.object({
-          code: t.text(),
-          language: t.text(),
+        args: z.object({
+          code: z.text(),
+          language: z.text(),
         }),
         handler: async ({ args }) => [
           {
@@ -99,9 +99,9 @@ describe("$prompt primitive", () => {
     class Prompts {
       typed = $prompt({
         description: "Typed prompt",
-        args: t.object({
-          name: t.text(),
-          count: t.number(),
+        args: z.object({
+          name: z.text(),
+          count: z.number(),
         }),
         handler: async ({ args }) => [
           {
@@ -129,8 +129,8 @@ describe("$prompt primitive", () => {
     class Prompts {
       validated = $prompt({
         description: "Validated prompt",
-        args: t.object({
-          required: t.text(),
+        args: z.object({
+          required: z.text(),
         }),
         handler: async ({ args }) => [{ role: "user", content: args.required }],
       });
@@ -172,8 +172,8 @@ describe("$prompt primitive", () => {
     class Prompts {
       conversation = $prompt({
         description: "Multi-turn prompt",
-        args: t.object({
-          topic: t.text(),
+        args: z.object({
+          topic: z.text(),
         }),
         handler: async ({ args }) => [
           { role: "user", content: `Let's discuss ${args.topic}` },
@@ -206,11 +206,9 @@ describe("$prompt primitive", () => {
       complex = $prompt({
         name: "complex-prompt",
         description: "A complex prompt with args",
-        args: t.object({
-          required: t.text({ description: "A required argument" }),
-          optional: t.optional(
-            t.number({ description: "An optional argument" }),
-          ),
+        args: z.object({
+          required: z.text({ description: "A required argument" }),
+          optional: z.number().describe("An optional argument").optional(),
         }),
         handler: async () => [{ role: "user", content: "test" }],
       });
@@ -288,9 +286,9 @@ describe("$prompt primitive", () => {
     class Prompts {
       optional = $prompt({
         description: "Prompt with optional args",
-        args: t.object({
-          name: t.text(),
-          style: t.optional(t.enum(["formal", "casual"])),
+        args: z.object({
+          name: z.text(),
+          style: z.enum(["formal", "casual"]).optional(),
         }),
         handler: async ({ args }) => [
           {
@@ -432,8 +430,8 @@ describe("$prompt primitive", () => {
     class Prompts {
       rolePrompt = $prompt({
         description: "Role-based prompt",
-        args: t.object({
-          task: t.text(),
+        args: z.object({
+          task: z.text(),
         }),
         handler: async ({ args, context }) => {
           const authContext = context?.data as AuthContext | undefined;

package/src/mcp/__tests__/$tool.spec.ts

@@ -1,4 +1,4 @@
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { describe, expect, test } from "vitest";
 import {
   $tool,
@@ -17,11 +17,11 @@ describe("$tool primitive", () => {
       add = $tool({
         description: "Add two numbers",
         schema: {
-          params: t.object({
-            a: t.number(),
-            b: t.number(),
+          params: z.object({
+            a: z.number(),
+            b: z.number(),
           }),
-          result: t.number(),
+          result: z.number(),
         },
         handler: async ({ params }) => params.a + params.b,
       });
@@ -66,11 +66,11 @@ describe("$tool primitive", () => {
       multiply = $tool({
         description: "Multiply two numbers",
         schema: {
-          params: t.object({
-            a: t.number(),
-            b: t.number(),
+          params: z.object({
+            a: z.number(),
+            b: z.number(),
           }),
-          result: t.number(),
+          result: z.number(),
         },
         handler: async ({ params }) => params.a * params.b,
       });
@@ -93,10 +93,10 @@ describe("$tool primitive", () => {
       greet = $tool({
         description: "Greet someone",
         schema: {
-          params: t.object({
-            name: t.text(),
+          params: z.object({
+            name: z.text(),
           }),
-          result: t.text(),
+          result: z.text(),
         },
         handler: async ({ params }) => `Hello, ${params.name}!`,
       });
@@ -119,8 +119,8 @@ describe("$tool primitive", () => {
       typed = $tool({
         description: "Typed tool",
         schema: {
-          params: t.object({
-            count: t.number(),
+          params: z.object({
+            count: z.number(),
           }),
         },
         handler: async ({ params }) => params.count * 2,
@@ -165,11 +165,11 @@ describe("$tool primitive", () => {
         name: "complex-tool",
         description: "A complex tool with params",
         schema: {
-          params: t.object({
-            required: t.text(),
-            optional: t.optional(t.number()),
+          params: z.object({
+            required: z.text(),
+            optional: z.number().optional(),
           }),
-          result: t.boolean(),
+          result: z.boolean(),
         },
         handler: async () => true,
       });
@@ -202,10 +202,10 @@ describe("$tool primitive", () => {
       async = $tool({
         description: "Async tool",
         schema: {
-          params: t.object({
-            delay: t.number(),
+          params: z.object({
+            delay: z.number(),
           }),
-          result: t.text(),
+          result: z.text(),
         },
         handler: async ({ params }) => {
           await new Promise((resolve) => setTimeout(resolve, params.delay));
@@ -375,7 +375,7 @@ describe("$tool primitive", () => {
       protected = $tool({
         description: "Protected tool",
         schema: {
-          result: t.text(),
+          result: z.text(),
         },
         handler: async ({ context }) => {
           const authHeader = context?.headers?.authorization;

package/src/mcp/__tests__/McpServerProvider.spec.ts

@@ -1,4 +1,4 @@
-import { Alepha, t } from "alepha";
+import { Alepha, z } from "alepha";
 import { describe, expect, test } from "vitest";
 import {
   $prompt,
@@ -163,13 +163,13 @@ describe("McpServerProvider", () => {
       class Calculator {
         add = $tool({
           description: "Add numbers",
-          schema: { params: t.object({ a: t.number(), b: t.number() }) },
+          schema: { params: z.object({ a: z.number(), b: z.number() }) },
           handler: async ({ params }) => params.a + params.b,
         });
 
         subtract = $tool({
           description: "Subtract numbers",
-          schema: { params: t.object({ a: t.number(), b: t.number() }) },
+          schema: { params: z.object({ a: z.number(), b: z.number() }) },
           handler: async ({ params }) => params.a - params.b,
         });
       }
@@ -201,8 +201,8 @@ describe("McpServerProvider", () => {
         multiply = $tool({
           description: "Multiply",
           schema: {
-            params: t.object({ a: t.number(), b: t.number() }),
-            result: t.number(),
+            params: z.object({ a: z.number(), b: z.number() }),
+            result: z.number(),
           },
           handler: async ({ params }) => params.a * params.b,
         });
@@ -482,7 +482,7 @@ describe("McpServerProvider", () => {
       class Prompts {
         greeting = $prompt({
           description: "Generate greeting",
-          args: t.object({ name: t.text() }),
+          args: z.object({ name: z.text() }),
           handler: async () => [],
         });
 
@@ -516,7 +516,7 @@ describe("McpServerProvider", () => {
       class Prompts {
         greeting = $prompt({
           description: "Generate greeting",
-          args: t.object({ name: t.text() }),
+          args: z.object({ name: z.text() }),
           handler: async ({ args }) => [
             { role: "user", content: `Say hello to ${args.name}` },
           ],
@@ -662,8 +662,8 @@ describe("McpServerProvider", () => {
         contextTool = $tool({
           description: "Tool that receives context",
           schema: {
-            params: t.object({ value: t.text() }),
-            result: t.text(),
+            params: z.object({ value: z.text() }),
+            result: z.text(),
           },
           handler: async ({ params, context }) => {
             receivedContext = context;
@@ -748,7 +748,7 @@ describe("McpServerProvider", () => {
       class Prompts {
         contextPrompt = $prompt({
           description: "Prompt that receives context",
-          args: t.object({ name: t.text() }),
+          args: z.object({ name: z.text() }),
           handler: async ({ args, context }) => {
             receivedContext = context;
             return [{ role: "user", content: `Hello ${args.name}` }];
@@ -819,7 +819,7 @@ describe("McpServerProvider", () => {
       class Tools {
         protected = $tool({
           description: "Protected tool",
-          schema: { result: t.text() },
+          schema: { result: z.text() },
           handler: async ({ context }) => {
             const auth = context?.headers?.authorization;
             if (!auth?.toString().startsWith("Bearer ")) {