feat(logs): collect Unity diagnostic logs + live-tail (refs unity-builder#740) (#23)

* feat(logs): collect Unity diagnostic logs + live-tail (issue game-ci/unity-builder#740)

Adds an opt-in, comprehensive Unity log/diagnostic collector and a live
log tailer to the orchestrator plugin lifecycle. Driven by Unity support
requests for files that live outside the project workspace and are
otherwise invisible to the artifact upload step.

Highlights
- UnityLogCollectorService walks a per-platform path registry covering
  Editor.log, Unity.Licensing.Client.log, Unity.Entitlements.Audit.log,
  services-config.json, Unity Hub info/error logs, editor crash dir,
  build report, bee_backend.log, Player.log, test results, IL2CPP
  output, ProjectVersion.txt, package manifest, macOS crash reports,
  and a Windows Event Log slice.
- Linux / macOS / Windows path templates with env-var expansion
  (HOME, USERPROFILE, LOCALAPPDATA, APPDATA, PROGRAMDATA, PROJECT,
  WORKSPACE), workspace-relative categories, and glob-aware path
  walking for Player.log / crash reports / wildcard ulf paths.
- Sensitive categories (license-file) excluded by default; opt-in via
  unityLogsIncludeSensitive.
- UnityLogTailService streams new lines from configured files to GHA
  log via core.info, with a per-file byte cap and recovery from file
  rotation. Defaults to <project>/Builds/Logs/Editor.log.
- buildContainerCopyScript() emits a shell snippet that copies Linux
  container-internal logs to a workspace-relative dir before the
  container exits, so host-side artifact upload picks them up.
- Wired into beforeLocalBuild (start tail) and afterLocalBuild (stop
  tail, run collector, register unity-logs output type).
- 9 vitest cases covering happy path, missing categories, sensitive
  gating, workspace-relative collection, category parsing, and live
  tail behaviour.
- Action inputs: collectUnityLogs, collectUnityLogsOnSuccess,
  unityLogCategories, unityLogsIncludeSensitive, unityLogsOutputDir,
  streamUnityLogs, streamUnityLogPaths.

Refs: game-ci/unity-builder#740

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(logs): convenient Logs facade + index re-exports

Adds a top-level Logs facade so library consumers can do:

  import { Logs } from '@game-ci/orchestrator';

  await Logs.collect({ outputDir: './bundle' });
  const tail = Logs.tail({ files: ['/path/Editor.log'] });
  tail.stop();
  Logs.categories(); // introspect available log categories

without reaching into model/orchestrator/services/output/. The
underlying UnityLogCollectorService and UnityLogTailService are now
also re-exported from src/index.ts alongside the path registry types,
so users who need fuller control still have direct access.

4 vitest cases covering collect/tail/category-introspection/parse.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: frostebite

action.yml

@@ -386,6 +386,60 @@ inputs:
     default: 'true'
     description: 'Add -disable-assembly-updater to batchmode launches to prevent ApiUpdater from destabilizing CI sessions.'
 
+  # ─── Unity diagnostic log collection ──────────────────────────────
+  collectUnityLogs:
+    required: false
+    default: 'false'
+    description: >
+      Collect Unity-internal logs (Editor.log, Unity.Licensing.Client.log,
+      Unity.Entitlements.Audit.log, services-config.json, Unity Hub logs,
+      crash dumps, build report, bee_backend.log, IL2CPP output, project
+      version, package manifest, etc.) into <workspace>/Logs/UnityDiagnostics/
+      after the build so they can be uploaded as artifacts and shared with
+      Unity support. See also: collectUnityLogsOnSuccess, unityLogCategories.
+  collectUnityLogsOnSuccess:
+    required: false
+    default: 'true'
+    description: >
+      When false, only collect Unity logs on non-zero exit codes. Default
+      true so successful builds also publish diagnostic artifacts (useful
+      for licensing audits and Unity support tickets).
+  unityLogCategories:
+    required: false
+    default: ''
+    description: >
+      Comma-separated subset of categories to collect (default = all
+      non-sensitive). Categories: editor-log, editor-prev-log,
+      licensing-client, entitlements-audit, services-config, unity-hub-info,
+      unity-hub-error, editor-crash, build-report, bee-backend, player-log,
+      test-results, il2cpp-output, project-version, package-manifest,
+      macos-crash-report, windows-event-log.
+  unityLogsIncludeSensitive:
+    required: false
+    default: 'false'
+    description: >
+      Include sensitive categories (e.g. license-file). NEVER enable in
+      public CI artifacts. Off by default.
+  unityLogsOutputDir:
+    required: false
+    default: ''
+    description: >
+      Override the output directory for collected Unity logs. Default is
+      <workspace>/Logs/UnityDiagnostics/.
+  streamUnityLogs:
+    required: false
+    default: 'false'
+    description: >
+      Live-tail Unity log files during the build and forward each new line
+      to the GitHub Actions log. Useful for long builds where you want to
+      see compile/import progress without waiting for the build to finish.
+  streamUnityLogPaths:
+    required: false
+    default: ''
+    description: >
+      Comma-separated list of files to live-tail. Defaults to the standard
+      <project>/Builds/Logs/Editor.log path that unity-builder configures.
+
   # ─── Build archive ─────────────────────────────────────────────────
   buildArchiveEnabled:
     required: false
@@ -795,6 +849,13 @@ runs:
         INPUT_ACCELERATORMODE: ${{ inputs.acceleratorMode }}
         INPUT_TESTRESULTCLEANUP: ${{ inputs.testResultCleanup }}
         INPUT_DISABLEASSEMBLYUPDATER: ${{ inputs.disableAssemblyUpdater }}
+        INPUT_COLLECTUNITYLOGS: ${{ inputs.collectUnityLogs }}
+        INPUT_COLLECTUNITYLOGSONSUCCESS: ${{ inputs.collectUnityLogsOnSuccess }}
+        INPUT_UNITYLOGCATEGORIES: ${{ inputs.unityLogCategories }}
+        INPUT_UNITYLOGSINCLUDESENSITIVE: ${{ inputs.unityLogsIncludeSensitive }}
+        INPUT_UNITYLOGSOUTPUTDIR: ${{ inputs.unityLogsOutputDir }}
+        INPUT_STREAMUNITYLOGS: ${{ inputs.streamUnityLogs }}
+        INPUT_STREAMUNITYLOGPATHS: ${{ inputs.streamUnityLogPaths }}
         INPUT_BUILDARCHIVEENABLED: ${{ inputs.buildArchiveEnabled }}
         INPUT_BUILDARCHIVEPATH: ${{ inputs.buildArchivePath }}
         INPUT_BUILDARCHIVERETENTION: ${{ inputs.buildArchiveRetention }}

src/index.ts

@@ -65,6 +65,30 @@ export { HotRunnerService } from './model/orchestrator/services/hot-runner';
 export { OutputService } from './model/orchestrator/services/output/output-service';
 export { OutputTypeRegistry } from './model/orchestrator/services/output/output-type-registry';
 export { ArtifactUploadHandler } from './model/orchestrator/services/output/artifact-upload-handler';
+export { Logs } from './model/orchestrator/services/output/logs-facade';
+export type {
+  LogsCollectOptions,
+  LogsTailHandle,
+} from './model/orchestrator/services/output/logs-facade';
+export { UnityLogCollectorService } from './model/orchestrator/services/output/unity-log-collector-service';
+export type {
+  UnityLogCollectionOptions,
+  UnityLogCollectionResult,
+  UnityLogCollectionResultItem,
+} from './model/orchestrator/services/output/unity-log-collector-service';
+export { UnityLogTailService } from './model/orchestrator/services/output/unity-log-tail-service';
+export type { UnityLogTailOptions } from './model/orchestrator/services/output/unity-log-tail-service';
+export {
+  UNITY_LOG_PATHS,
+  getUnityLogPath,
+  listAllUnityLogCategories,
+  listSafeUnityLogCategories,
+} from './model/orchestrator/services/output/unity-log-paths';
+export type {
+  UnityLogCategory,
+  UnityLogPathDefinition,
+  UnityLogPlatform,
+} from './model/orchestrator/services/output/unity-log-paths';
 export { IncrementalSyncService } from './model/orchestrator/services/sync';
 
 // Advanced services (lazy-loaded by unity-builder plugin interface)

src/model/orchestrator/services/output/logs-facade.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Logs } from './logs-facade';
+
+function makeTempRoot(prefix: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+describe('Logs facade', () => {
+  let workspace: string;
+  let fakeHome: string;
+
+  beforeEach(() => {
+    workspace = makeTempRoot('logs-facade-ws-');
+    fakeHome = makeTempRoot('logs-facade-home-');
+  });
+
+  afterEach(() => {
+    fs.rmSync(workspace, { recursive: true, force: true });
+    fs.rmSync(fakeHome, { recursive: true, force: true });
+  });
+
+  it('collect() forwards to UnityLogCollectorService and returns a result', async () => {
+    const unity3d = path.join(fakeHome, '.config', 'unity3d');
+    fs.mkdirSync(path.join(unity3d, 'Unity'), { recursive: true });
+    fs.writeFileSync(path.join(unity3d, 'Editor.log'), 'editor');
+
+    const result = await Logs.collect({
+      workspace,
+      projectPath: workspace,
+      platform: 'linux',
+      env: { HOME: fakeHome } as NodeJS.ProcessEnv,
+      categories: ['editor-log'],
+    });
+
+    expect(result.collected.map((c) => c.category)).toEqual(['editor-log']);
+    expect(fs.existsSync(result.manifestPath)).toBe(true);
+  });
+
+  it('tail() returns a stop handle', async () => {
+    const filePath = path.join(workspace, 'Editor.log');
+    fs.writeFileSync(filePath, 'first line\n');
+
+    const lines: string[] = [];
+    const handle = Logs.tail({
+      files: [filePath],
+      onLine: (_file, line) => lines.push(line),
+      pollIntervalMs: 50,
+      prefixWithFilename: false,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    fs.appendFileSync(filePath, 'second\n');
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    handle.stop();
+
+    expect(lines).toContain('first line');
+    expect(lines).toContain('second');
+  });
+
+  it('exposes category introspection helpers', () => {
+    const all = Logs.allCategoryIds();
+    const safe = Logs.safeCategoryIds();
+
+    expect(all).toContain('editor-log');
+    expect(all).toContain('license-file');
+    expect(safe).toContain('editor-log');
+    expect(safe).not.toContain('license-file');
+
+    const categories = Logs.categories();
+    expect(categories.length).toBe(all.length);
+    const editor = categories.find((c) => c.category === 'editor-log');
+    expect(editor?.description).toMatch(/Editor\.log/);
+  });
+
+  it('parseCategories drops unknown entries', () => {
+    expect(Logs.parseCategories('editor-log,bogus,licensing-client')).toEqual([
+      'editor-log',
+      'licensing-client',
+    ]);
+    expect(Logs.parseCategories('all')).toBeUndefined();
+    expect(Logs.parseCategories('')).toBeUndefined();
+  });
+});

src/model/orchestrator/services/output/logs-facade.ts

@@ -0,0 +1,126 @@
+import path from 'node:path';
+import {
+  UnityLogCollectorService,
+  UnityLogCollectionOptions,
+  UnityLogCollectionResult,
+} from './unity-log-collector-service';
+import {
+  UNITY_LOG_PATHS,
+  UnityLogCategory,
+  UnityLogPathDefinition,
+  listAllUnityLogCategories,
+  listSafeUnityLogCategories,
+} from './unity-log-paths';
+import { UnityLogTailService, UnityLogTailOptions } from './unity-log-tail-service';
+
+export interface LogsCollectOptions extends Omit<
+  UnityLogCollectionOptions,
+  'workspace' | 'projectPath'
+> {
+  /** Workspace root. Defaults to process.cwd(). */
+  workspace?: string;
+  /** Project path. Defaults to workspace. */
+  projectPath?: string;
+}
+
+export interface LogsTailHandle {
+  /** Stop the tail and flush any buffered partial line. */
+  stop(): void;
+}
+
+/**
+ * Convenience facade over the Unity log collection + tailing services.
+ *
+ * Lets library consumers do:
+ *
+ *   import { Logs } from '@game-ci/orchestrator';
+ *
+ *   const result = await Logs.collect({ outputDir: './unity-bundle' });
+ *   const tail = Logs.tail({ files: ['/path/to/Editor.log'] });
+ *   tail.stop();
+ *
+ * without reaching into `model/orchestrator/services/output/...`. The
+ * underlying `UnityLogCollectorService` and `UnityLogTailService` remain
+ * exported for users who need fuller control.
+ */
+export class Logs {
+  /**
+   * Collect Unity-internal logs into an artifact directory. Returns the
+   * collection result (collected/missing items + manifest path + total bytes).
+   *
+   * Defaults workspace to `process.cwd()` and projectPath to workspace, so a
+   * one-liner like `await Logs.collect()` works on a runner host.
+   */
+  static async collect(options: LogsCollectOptions = {}): Promise<UnityLogCollectionResult> {
+    const workspace = options.workspace || process.cwd();
+    const projectPath = options.projectPath || workspace;
+
+    return UnityLogCollectorService.collect({
+      ...options,
+      workspace,
+      projectPath,
+    });
+  }
+
+  /**
+   * Live-tail one or more Unity log files. Returns a handle with `stop()`.
+   *
+   * If `files` is omitted, tails the unity-builder default
+   * `<projectPath>/Builds/Logs/Editor.log` and the orchestrator-collected
+   * `<workspace>/Logs/UnityDiagnostics/editor-log/Editor.log` once it lands.
+   */
+  static tail(
+    options: Partial<UnityLogTailOptions> & {
+      workspace?: string;
+      projectPath?: string;
+    } = {},
+  ): LogsTailHandle {
+    const workspace = options.workspace || process.cwd();
+    const projectPath = options.projectPath || workspace;
+    const files =
+      options.files && options.files.length > 0
+        ? options.files
+        : [
+            path.join(projectPath, 'Builds', 'Logs', 'Editor.log'),
+            path.join(workspace, 'Logs', 'UnityDiagnostics', 'editor-log', 'Editor.log'),
+          ];
+
+    const service = new UnityLogTailService({
+      ...options,
+      files,
+    });
+    service.start();
+    return { stop: () => service.stop() };
+  }
+
+  /**
+   * List every known log category with its description and sensitivity flag.
+   * Useful for building UIs/CLIs that surface what `Logs.collect()` will pick up.
+   */
+  static categories(): UnityLogPathDefinition[] {
+    return UNITY_LOG_PATHS.slice();
+  }
+
+  /**
+   * List safe (non-sensitive) category identifiers — the default set when
+   * `categories` is omitted from `Logs.collect`.
+   */
+  static safeCategoryIds(): UnityLogCategory[] {
+    return listSafeUnityLogCategories();
+  }
+
+  /**
+   * List every category identifier including sensitive ones.
+   */
+  static allCategoryIds(): UnityLogCategory[] {
+    return listAllUnityLogCategories();
+  }
+
+  /**
+   * Parse a comma-separated category list string (e.g. from a CLI flag),
+   * dropping unknown entries and treating "all"/empty as "default set".
+   */
+  static parseCategories(input: string | undefined): UnityLogCategory[] | undefined {
+    return UnityLogCollectorService.parseCategories(input);
+  }
+}