Merge pull request #268 from wttech/copilot/add-timestamped-output-methods

Add timestamped output methods to CodePrintStream

Author: krystian-panek-vmltech

README.md

@@ -57,6 +57,10 @@ It works seamlessly across AEM on-premise, AMS, and AEMaaCS environments.
       - [Minimal example](#minimal-example)
       - [Inputs example](#inputs-example)
       - [Outputs example](#outputs-example)
+      - [Console \& logging](#console--logging)
+        - [Simple console output](#simple-console-output)
+        - [Timestamped console output](#timestamped-console-output)
+        - [Logged console output](#logged-console-output)
       - [ACL example](#acl-example)
       - [Repo example](#repo-example)
       - [Abortable example](#abortable-example)
@@ -350,6 +354,58 @@ outputs.text("configJson") {
 }
 ```
 
+#### Console & logging
+
+Scripts provide three different ways to write messages to the console and logs, each serving different purposes:
+
+##### Simple console output
+
+Use `println` or `printf` for simple console output without timestamps or log levels. This is useful for quick debugging or generating simple text output.
+
+```groovy
+void doRun() {
+    println "Simple message without timestamp"
+    printf "Formatted: %s = %d\n", "count", 42
+}
+```
+
+##### Timestamped console output
+
+Use `out.error()`, `out.warn()`, `out.info()`, `out.debug()`, `out.trace()` to write messages to the console with timestamps and log levels. These messages appear only in the execution console and are not persisted to AEM logs.
+
+```groovy
+void doRun() {
+    out.error "Failed to process resource: ${resource.path}"
+    out.warn "Resource ${resource.path} is missing required property"
+    out.info "Processing started"
+    out.debug "Processing resource: ${resource.path}"
+    out.trace "Entering method with params: ${params}"
+}
+```
+
+##### Logged console output
+
+Use `log.error()`, `log.warn()`, `log.info()`, `log.debug()`, `log.trace()` to write messages both to the console and to AEM logs (e.g., error.log). This is recommended for production scripts where you need persistent log records.
+
+```groovy
+void doRun() {
+    log.info "Doing regular stuff"
+    
+    try {
+        // ... risky logic
+        log.info "Doing risky stuff ended"
+    } catch (Exception e) {
+        log.error "Doing risky stuff failed: ${e.message}", e
+    }
+}
+```
+
+**Best practices:**
+
+- Use `println` / `printf` for quick debugging or simple text generation
+- Use `out.*` for console-only feedback during script execution (progress indicators, status updates)
+- Use `log.*` for important events that should be persisted in AEM logs (errors, warnings, critical operations)
+
 #### ACL example
 
 The following example of the automatic script demonstrates how to create a user and a group, assign permissions, and add members to the group using the [ACL service](https://github.com/wttech/acm/blob/main/core/src/main/java/dev/vml/es/acm/core/acl/Acl.java) (`acl`).

core/src/main/java/dev/vml/es/acm/core/code/CodePrintLevel.java

@@ -0,0 +1,24 @@
+package dev.vml.es.acm.core.code;
+
+import java.util.Arrays;
+import java.util.Optional;
+
+public enum CodePrintLevel {
+    INFO,
+    ERROR,
+    WARN,
+    DEBUG,
+    TRACE;
+
+    public static Optional<CodePrintLevel> find(String level) {
+        return Arrays.stream(values())
+                .filter(l -> l.name().equalsIgnoreCase(level))
+                .findFirst();
+    }
+
+    public static CodePrintLevel of(String level) {
+        return find(level)
+                .orElseThrow(() ->
+                        new IllegalArgumentException(String.format("Code print level '%s' is not supported!", level)));
+    }
+}

core/src/main/java/dev/vml/es/acm/core/code/CodePrintStream.java

@@ -146,4 +146,34 @@ public void fromLoggers(String... loggerNames) {
     public void fromLoggers(List<String> loggerNames) {
         loggerNames.forEach(this::fromLogger);
     }
+
+    public void info(String message) {
+        printStamped(CodePrintLevel.INFO, message);
+    }
+
+    public void error(String message) {
+        printStamped(CodePrintLevel.ERROR, message);
+    }
+
+    public void warn(String message) {
+        printStamped(CodePrintLevel.WARN, message);
+    }
+
+    public void debug(String message) {
+        printStamped(CodePrintLevel.DEBUG, message);
+    }
+
+    public void trace(String message) {
+        printStamped(CodePrintLevel.TRACE, message);
+    }
+
+    public void printStamped(String level, String message) {
+        printStamped(CodePrintLevel.of(level), message);
+    }
+
+    public void printStamped(CodePrintLevel level, String message) {
+        LocalDateTime now = LocalDateTime.now();
+        String timestamp = now.format(LOGGER_TIMESTAMP_FORMATTER);
+        println(timestamp + " [" + level + "] " + message);
+    }
 }

core/src/test/java/dev/vml/es/acm/core/code/CodePrintStreamTest.java

@@ -0,0 +1,105 @@
+package dev.vml.es.acm.core.code;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import ch.qos.logback.classic.LoggerContext;
+import java.io.ByteArrayOutputStream;
+import org.junit.jupiter.api.Test;
+import org.slf4j.LoggerFactory;
+
+class CodePrintStreamTest {
+
+    @Test
+    void shouldPrintInfoWithTimestamp() {
+        if (!(LoggerFactory.getILoggerFactory() instanceof LoggerContext)) {
+            return;
+        }
+
+        ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
+        CodePrintStream printStream = new CodePrintStream(outputStream, "test-id");
+
+        printStream.info("Test info message");
+
+        String output = outputStream.toString();
+        assertTrue(output.matches("\\d{2}:\\d{2}:\\d{2}\\.\\d{3} \\[INFO\\] Test info message\\R"));
+    }
+
+    @Test
+    void shouldPrintErrorWithTimestamp() {
+        if (!(LoggerFactory.getILoggerFactory() instanceof LoggerContext)) {
+            return;
+        }
+
+        ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
+        CodePrintStream printStream = new CodePrintStream(outputStream, "test-id");
+
+        printStream.error("Test error message");
+
+        String output = outputStream.toString();
+        assertTrue(output.matches("\\d{2}:\\d{2}:\\d{2}\\.\\d{3} \\[ERROR\\] Test error message\\R"));
+    }
+
+    @Test
+    void shouldPrintWarnWithTimestamp() {
+        if (!(LoggerFactory.getILoggerFactory() instanceof LoggerContext)) {
+            return;
+        }
+
+        ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
+        CodePrintStream printStream = new CodePrintStream(outputStream, "test-id");
+
+        printStream.warn("Test warn message");
+
+        String output = outputStream.toString();
+        assertTrue(output.matches("\\d{2}:\\d{2}:\\d{2}\\.\\d{3} \\[WARN\\] Test warn message\\R"));
+    }
+
+    @Test
+    void shouldPrintDebugWithTimestamp() {
+        if (!(LoggerFactory.getILoggerFactory() instanceof LoggerContext)) {
+            return;
+        }
+
+        ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
+        CodePrintStream printStream = new CodePrintStream(outputStream, "test-id");
+
+        printStream.debug("Test debug message");
+
+        String output = outputStream.toString();
+        assertTrue(output.matches("\\d{2}:\\d{2}:\\d{2}\\.\\d{3} \\[DEBUG\\] Test debug message\\R"));
+    }
+
+    @Test
+    void shouldPrintTraceWithTimestamp() {
+        if (!(LoggerFactory.getILoggerFactory() instanceof LoggerContext)) {
+            return;
+        }
+
+        ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
+        CodePrintStream printStream = new CodePrintStream(outputStream, "test-id");
+
+        printStream.trace("Test trace message");
+
+        String output = outputStream.toString();
+        assertTrue(output.matches("\\d{2}:\\d{2}:\\d{2}\\.\\d{3} \\[TRACE\\] Test trace message\\R"));
+    }
+
+    @Test
+    void shouldPrintMultipleMessagesWithDifferentLevels() {
+        if (!(LoggerFactory.getILoggerFactory() instanceof LoggerContext)) {
+            return;
+        }
+
+        ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
+        CodePrintStream printStream = new CodePrintStream(outputStream, "test-id");
+
+        printStream.info("Info message");
+        printStream.error("Error message");
+        printStream.warn("Warn message");
+
+        String output = outputStream.toString();
+        assertTrue(output.contains("[INFO] Info message"));
+        assertTrue(output.contains("[ERROR] Error message"));
+        assertTrue(output.contains("[WARN] Warn message"));
+    }
+}

ui.content/src/main/content/jcr_root/conf/acm/settings/snippet/available/core/general/demo_processing.yml

@@ -6,17 +6,17 @@ content: |
   }
     
   void doRun() {
-    println "Processing..."
+    out.info "Processing..."
     
-    println "Updating resources..."
+    out.info "Updating resources..."
     def max = 20
     for (int i = 0; i < max; i++) {
       context.checkAborted()
       Thread.sleep(1000)
-      println "Updated (\${i + 1}/\${max})"
+      out.info "Updated (\${i + 1}/\${max})"
     }
     
-    println "Processing done"
+    out.info "Processing done"
   }
 documentation: |
   A skeleton for a script that simulates a processing task.