unity-cli@v1.5.6

- updated GitHub annotation handling
  - added unit tests
  - added docs
- bump deps

Author: StephenHodgson

README.md

@@ -28,6 +28,9 @@ A powerful command line utility for the Unity Game Engine. Automate Unity projec
       - [Run Unity Editor Commands](#run-unity-editor-commands)
     - [Unity Package Manager](#unity-package-manager)
       - [Sign a Unity Package](#sign-a-unity-package)
+- [Logging](#logging)
+  - [Local cli](#local-cli)
+  - [Github Actions](#github-actions)
 
 ## Features
 
@@ -288,3 +291,37 @@ unity-cli run --unity-project <path-to-project> -quit -batchmode -executeMethod
 ```bash
 unity-cli sign-package --package <path-to-package-folder> --email <your-email> --password <your-password> --organization <your-organization-id>
 ```
+
+## Logging
+
+### Local cli
+
+`unity-cli` keeps regular terminal runs simple:
+
+- Writes everything to `stdout` with ANSI colors (yellow warnings, red errors) so you can scan logs quickly.
+- `startGroup`/`endGroup` just print headers and content, and don't include any foldouts or collapsing behavior and is meant for CI environments only.
+
+### Github Actions
+
+When `GITHUB_ACTIONS=true`, the logger emits GitHub workflow commands automatically:
+
+- Defaults to `info` level; add `--verbose` (or temporarily set `ACTIONS_STEP_DEBUG=true`) to surface `debug` lines.
+- `Logger.annotate(...)` escapes `%`, `\r`, and `\n`, then includes `file`, `line`, `endLine`, `col`, `endColumn`, and `title` metadata so annotations are clickable in the Checks UI.
+- `startGroup`/`endGroup` become `::group::` / `::endgroup::` blocks.
+- Helper methods (`CI_mask`, `CI_setEnvironmentVariable`, `CI_setOutput`, `CI_appendWorkflowSummary`) write to the corresponding GitHub-provided files, so secrets stay masked and workflow outputs update automatically.
+
+The same command line you run locally therefore produces colorized console output on your machine and rich annotations once it runs inside Actions.
+
+### Additional CI Environments
+
+At the moment, only GitHub Actions is supported for enhanced logging. If you would like to see support for additional CI environments, please open a pull request or feature request on the GitHub repository.
+
+#### Roadmap
+
+- [ ] Support Azure DevOps logging commands
+- [ ] Support GitLab CI logging commands
+- [ ] Support Bitbucket Pipelines logging commands
+- [ ] Support Jenkins logging commands
+- [ ] Support CircleCI logging commands
+- [ ] Support Travis CI logging commands
+- [ ] Support TeamCity logging commands

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@rage-against-the-pixel/unity-cli",
-  "version": "1.5.5",
+  "version": "1.5.6",
   "description": "A command line utility for the Unity Game Engine.",
   "author": "RageAgainstThePixel",
   "license": "MIT",
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "@electron/asar": "^4.0.1",
-    "@rage-against-the-pixel/unity-releases-api": "^1.0.3",
+    "@rage-against-the-pixel/unity-releases-api": "^1.0.4",
     "commander": "^14.0.2",
     "glob": "^11.1.0",
     "semver": "^7.7.3",

package.json

@@ -152,56 +152,55 @@ export class Logger {
 
         switch (this._ci) {
             case 'GITHUB_ACTIONS': {
-                var level: string;
-                switch (logLevel) {
-                    case LogLevel.CI:
-                    case LogLevel.INFO:
-                    case LogLevel.DEBUG: {
-                        level = 'notice';
-                        break;
-                    }
-                    case LogLevel.WARN: {
-                        level = 'warning';
-                        break;
-                    }
-                    case LogLevel.ERROR: {
-                        level = 'error';
-                        break;
-                    }
-                }
+                const level = {
+                    [LogLevel.CI]: 'notice',
+                    [LogLevel.INFO]: 'notice',
+                    [LogLevel.DEBUG]: 'notice',
+                    [LogLevel.WARN]: 'warning',
+                    [LogLevel.ERROR]: 'error',
+                }[logLevel] ?? 'notice';
 
-                let parts: string[] = [];
-
-                if (file !== undefined && file.length > 0) {
-                    parts.push(`file=${file}`);
-                }
+                const parts: string[] = [];
+                const appendPart = (key: string, value?: string | number): void => {
+                    if (value === undefined || value === null) { return; }
+                    const stringValue = value.toString();
+                    if (stringValue.length === 0) { return; }
+                    parts.push(`${key}=${this.escapeGitHubCommandValue(stringValue)}`);
+                };
 
+                appendPart('file', file);
                 if (line !== undefined && line > 0) {
-                    parts.push(`line=${line}`);
+                    appendPart('line', line);
                 }
-
                 if (endLine !== undefined && endLine > 0) {
-                    parts.push(`endLine=${endLine}`);
+                    appendPart('endLine', endLine);
                 }
-
                 if (column !== undefined && column > 0) {
-                    parts.push(`col=${column}`);
+                    appendPart('col', column);
                 }
-
                 if (endColumn !== undefined && endColumn > 0) {
-                    parts.push(`endColumn=${endColumn}`);
-                }
-
-                if (title !== undefined && title.length > 0) {
-                    parts.push(`title=${title}`);
+                    appendPart('endColumn', endColumn);
                 }
+                appendPart('title', title);
 
-                annotation = `::${level} ${parts.join(',')}::${message}`;
+                const metadata = parts.length > 0 ? ` ${parts.join(',')}` : '';
+                annotation = `::${level}${metadata}::${this.escapeGitHubCommandValue(message)}`;
                 break;
             }
         }
 
-        process.stdout.write(`${annotation}\n`);
+        if (annotation.length > 0) {
+            process.stdout.write(`${annotation}\n`);
+        } else {
+            this.log(logLevel, message);
+        }
+    }
+
+    private escapeGitHubCommandValue(value: string): string {
+        return value
+            .replace(/%/g, '%25')
+            .replace(/\r/g, '%0D')
+            .replace(/\n/g, '%0A');
     }
 
     private shouldLog(level: LogLevel): boolean {

src/logging.ts

@@ -0,0 +1,58 @@
+type LoggingModule = typeof import('../src/logging');
+
+describe('Logger annotate', () => {
+    const ORIGINAL_ENV = process.env;
+
+    const loadLoggingModule = (): LoggingModule => {
+        return require('../src/logging') as LoggingModule;
+    };
+
+    beforeEach(() => {
+        jest.resetModules();
+        process.env = { ...ORIGINAL_ENV };
+    });
+
+    afterEach(() => {
+        process.env = ORIGINAL_ENV;
+        jest.restoreAllMocks();
+    });
+
+    it('formats annotations correctly for GitHub Actions', () => {
+        process.env.GITHUB_ACTIONS = 'true';
+        const logging = loadLoggingModule();
+        const writeSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+
+        logging.Logger.instance.annotate(
+            logging.LogLevel.ERROR,
+            'Line one\nLine two',
+            'src/file.ts',
+            7,
+            undefined,
+            undefined,
+            undefined,
+            'Build failed'
+        );
+
+        expect(writeSpy).toHaveBeenCalledWith('::error file=src/file.ts,line=7,title=Build failed::Line one%0ALine two\n');
+    });
+
+    it('omits metadata spacing when none is provided', () => {
+        process.env.GITHUB_ACTIONS = 'true';
+        const logging = loadLoggingModule();
+        const writeSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+
+        logging.Logger.instance.annotate(logging.LogLevel.INFO, 'Hello world');
+
+        expect(writeSpy).toHaveBeenCalledWith('::notice::Hello world\n');
+    });
+
+    it('falls back to standard logging when annotations are unavailable', () => {
+        delete process.env.GITHUB_ACTIONS;
+        const logging = loadLoggingModule();
+        const writeSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+
+        logging.Logger.instance.annotate(logging.LogLevel.INFO, 'Hello local');
+
+        expect(writeSpy).toHaveBeenCalledWith('Hello local\n');
+    });
+});