@quenty/nevermore-cli 4.43.3 → 4.44.0

package/src/utils/job-context/job-context.ts

@@ -1,4 +1,24 @@
 import { type BuildPlaceOptions, type BuiltPlace } from '../build/build.js';
+import { type StructuredTestResults } from '../testing/structured-test-results.js';
+import { type LogFetchStats } from '../testing/log-fetch-stats.js';
+import { type TaskLogMessage } from '../open-cloud/open-cloud-client.js';
+
+/** A run's output, with the severity and the fetch that produced it. */
+export interface JobLogs {
+  text: string;
+  /**
+   * The same output split into typed messages, when the transport reports
+   * severity. Empty for one that does not — a local run reads its logs off the
+   * Studio bridge, which says only what was printed.
+   */
+  messages: TaskLogMessage[];
+  /**
+   * What collecting them took, when the transport can say. Absent rather than
+   * zeroed, so "no fetch to measure" cannot read as "a fetch that found
+   * nothing".
+   */
+  stats?: LogFetchStats;
+}
 
 export type { BuiltPlace } from '../build/build.js';
 
@@ -28,6 +48,48 @@ export interface ScriptRunResult {
   taskState?: string;
   /** Error message from the execution backend, if any. */
   errorMessage?: string;
+  /**
+   * Everything the executed script returned, in order — the structured channel
+   * out of a run, as opposed to its printed output. Engine logs are truncated
+   * by Open Cloud on long runs, so anything a caller must read back exactly
+   * belongs here rather than in the log text.
+   *
+   * `undefined` means the transport never delivered a return channel: a cloud
+   * task that ended without an `output` (a FAILED task carries none, and an
+   * oversize return value fails the task rather than truncating the value), a
+   * bridge run that timed out or disconnected, or a context that does not
+   * carry return values at all. That is deliberately distinct from `[]`, which
+   * means the script ran and returned nothing — a caller that needs the value
+   * can fall back to parsing logs in the first case but not the second.
+   *
+   * Values are JSON-shaped, but the two transports spell exotic Luau types
+   * differently: Open Cloud auto-serializes them, while the Studio bridge
+   * marshals them into `{ type, value }` wrappers (`SerializedReturnValue`).
+   * Plain tables of strings, numbers and booleans come back identically on
+   * both, so structured results should stay inside that subset.
+   */
+  returnValues?: unknown[];
+  /**
+   * The run's structured test results, when the context resolved them itself
+   * rather than leaving them in `returnValues` for the caller to decode.
+   *
+   * Only aggregated batch mode sets this: one execution covers every package, so
+   * its return value belongs to no single one of them and the per-package
+   * results have to be recovered from the batch summary first. A context that
+   * sets this has also reported where the counts came from, so the caller does
+   * not report it a second time.
+   */
+  testResults?: StructuredTestResults;
+  /**
+   * True when this run's verdict rests on returned results alone, its log
+   * output having been dropped before it reached us.
+   *
+   * A narrower verdict than an ordinary one: the counts are exact, but with no
+   * text there is nothing to check for tracebacks and nothing to read when
+   * something did go wrong. Reported so it can be shown as such rather than as
+   * an ordinary pass.
+   */
+  logsLost?: boolean;
 }
 
 /**
@@ -50,8 +112,15 @@ export interface JobContext {
     options: RunScriptOptions
   ): Promise<ScriptRunResult>;
 
-  /** Retrieve raw logs from the most recent script execution on this deployment. */
-  getLogsAsync(deployment: Deployment): Promise<string>;
+  /**
+   * Everything the most recent script execution printed.
+   *
+   * One value rather than a log plus two optional side-channels for its
+   * severity and its fetch: they all come from the same fetch, so returning
+   * them together removes both the chance of asking a context that does not
+   * implement one and the chance of handing an accessor the wrong handle.
+   */
+  getLogsAsync(deployment: Deployment): Promise<JobLogs>;
 
   /** Release a single deployment (stop bridge / clear task metadata). */
   releaseAsync(deployment: Deployment): Promise<void>;

package/src/utils/job-context/local-job-context.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Unit tests for LocalJobContext.runScriptAsync — validates that a bridge run
+ * hands its script return values on as a ScriptRunResult, and that a run which
+ * never completed reports none rather than an empty result.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { type Reporter } from '@quenty/cli-output-helpers/reporting';
+import { LocalJobContext } from './local-job-context.js';
+import { type Deployment } from './job-context.js';
+
+function createReporter(): Reporter {
+  return {
+    onPackagePhaseChange: vi.fn(),
+    onPackageProgressUpdate: vi.fn(),
+    onPackageStart: vi.fn(),
+    onPackageResult: vi.fn(),
+  } as unknown as Reporter;
+}
+
+/**
+ * The deployment handle is private to the context, so the test stands in a
+ * bridge with the one method runScriptAsync calls on it.
+ */
+function createDeployment(
+  executeAsync: () => Promise<{
+    success: boolean;
+    logs: string;
+    returnValues?: unknown[];
+  }>
+): Deployment {
+  return {
+    bridge: { executeAsync },
+    cachedLogs: '',
+  } as unknown as Deployment;
+}
+
+describe('LocalJobContext.runScriptAsync', () => {
+  it('reports the values the script returned', async () => {
+    const context = new LocalJobContext(createReporter());
+    const deployment = createDeployment(async () => ({
+      success: true,
+      logs: 'ran',
+      returnValues: [{ counts: { passed: 7 } }],
+    }));
+
+    const result = await context.runScriptAsync(deployment, {
+      scriptContent: 'return results',
+      packageName: 'maid',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.returnValues).toEqual([{ counts: { passed: 7 } }]);
+    expect((await context.getLogsAsync(deployment)).text).toBe('ran');
+  });
+
+  it('leaves returnValues absent when the bridge reported none', async () => {
+    const context = new LocalJobContext(createReporter());
+    const deployment = createDeployment(async () => ({
+      success: false,
+      logs: '[StudioBridge] Timed out after 200ms',
+    }));
+
+    const result = await context.runScriptAsync(deployment, {
+      scriptContent: 'while true do end',
+      packageName: 'maid',
+    });
+
+    expect(result.returnValues).toBeUndefined();
+  });
+
+  it('leaves returnValues absent when the bridge throws', async () => {
+    const context = new LocalJobContext(createReporter());
+    const deployment = createDeployment(async () => {
+      throw new Error('no connected client');
+    });
+
+    const result = await context.runScriptAsync(deployment, {
+      scriptContent: 'return results',
+      packageName: 'maid',
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.returnValues).toBeUndefined();
+    expect((await context.getLogsAsync(deployment)).text).toContain(
+      'no connected client'
+    );
+  });
+});

package/src/utils/job-context/local-job-context.ts

@@ -6,6 +6,7 @@ import {
   type DeployPlaceOptions,
   type RunScriptOptions,
   type ScriptRunResult,
+  type JobLogs,
 } from './job-context.js';
 import { type BasePlaceResolver } from '@quenty/nevermore-deploy';
 import { BaseJobContext } from './base-job-context.js';
@@ -69,7 +70,7 @@ export class LocalJobContext extends BaseJobContext {
         timeoutMs,
       });
       localDeployment.cachedLogs = result.logs;
-      return { success: result.success };
+      return { success: result.success, returnValues: result.returnValues };
     } catch (error) {
       const errorMessage =
         error instanceof Error ? error.message : String(error);
@@ -78,9 +79,12 @@ export class LocalJobContext extends BaseJobContext {
     }
   }
 
-  async getLogsAsync(deployment: Deployment): Promise<string> {
+  async getLogsAsync(deployment: Deployment): Promise<JobLogs> {
     const localDeployment = deployment as LocalDeployment;
-    return localDeployment.cachedLogs;
+
+    // No severity and no fetch: the bridge hands over text it already has.
+    // Both stay absent rather than being invented.
+    return { text: localDeployment.cachedLogs, messages: [] };
   }
 
   async releaseAsync(deployment: Deployment): Promise<void> {

package/src/utils/open-cloud/open-cloud-client.test.ts

@@ -1,6 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import * as fs from 'fs/promises';
-import { OpenCloudClient } from './open-cloud-client.js';
+import {
+  OpenCloudClient,
+  getTaskReturnValues,
+  type LuauTask,
+} from './open-cloud-client.js';
 import type { RateLimiter } from './rate-limiter.js';
 
 vi.mock('@quenty/cli-output-helpers', () => ({
@@ -367,3 +371,153 @@ describe('OpenCloudClient.resolveLatestPlaceVersionAsync', () => {
     ).rejects.toThrowError(/unparseable version path/);
   });
 });
+
+describe('getTaskReturnValues', () => {
+  function makeTask(overrides: Partial<LuauTask>): LuauTask {
+    return {
+      path: 'universes/1/places/2/versions/3/luau-execution-session-tasks/4',
+      createTime: '2026-01-01T00:00:00Z',
+      updateTime: '2026-01-01T00:01:00Z',
+      user: 'users/1',
+      state: 'COMPLETE',
+      script: 'return 1',
+      ...overrides,
+    };
+  }
+
+  it('returns the values natively typed, one entry per returned value', () => {
+    // Roblox serializes the return value itself, so a returned table arrives as
+    // real nested JSON — there is no JSON string to parse a second time.
+    const task = makeTask({
+      output: {
+        results: [{ slug: 'maid', counts: { passed: 1014 } }, 'str', 42, true],
+      },
+    });
+
+    expect(getTaskReturnValues(task)).toEqual([
+      { slug: 'maid', counts: { passed: 1014 } },
+      'str',
+      42,
+      true,
+    ]);
+  });
+
+  it('reports an empty result when the task returned nothing', () => {
+    expect(getTaskReturnValues(makeTask({ output: {} }))).toEqual([]);
+  });
+
+  it('reports undefined when a failed task carried no output at all', () => {
+    // An oversize return value fails the task with no output and no error
+    // message, so "nothing came back to read" has to stay distinguishable from
+    // "the script returned nothing" — only the former can fall back to logs.
+    const task = makeTask({ state: 'FAILED', output: undefined });
+
+    expect(getTaskReturnValues(task)).toBeUndefined();
+  });
+});
+
+describe('OpenCloudClient.getRawTaskLogsAsync', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  /**
+   * Page the logs endpoint the way the real one does: many messages inside each
+   * `luauExecutionSessionTaskLog`, and pagination over those entries rather than
+   * over messages.
+   */
+  function makeLogsLimiter(
+    pages: Array<Array<string[]>>,
+    urls: string[] = []
+  ): RateLimiter {
+    return {
+      fetchAsync: vi.fn(async (url: string | URL) => {
+        urls.push(String(url));
+        const page = pages[urls.length - 1] ?? [];
+        return new Response(
+          JSON.stringify({
+            luauExecutionSessionTaskLogs: page.map((messages) => ({
+              structuredMessages: messages.map((message) => ({
+                message,
+                createTime: '2026-08-27T00:00:00.38Z',
+                messageType: 'OUTPUT',
+              })),
+            })),
+            ...(urls.length < pages.length
+              ? { nextPageToken: `token-${urls.length}` }
+              : {}),
+          }),
+          { status: 200 }
+        );
+      }),
+    } as unknown as RateLimiter;
+  }
+
+  it('counts pages, entries and messages separately', async () => {
+    // Entries are not lines: the endpoint's page size applies to the log
+    // objects, each of which carries many messages. Conflating the two reads a
+    // 2-entry response as a 2-line run.
+    const client = new OpenCloudClient({
+      apiKey: 'test-key',
+      rateLimiter: makeLogsLimiter([[['a', 'b', 'c'], ['d']], [['e', 'f']]]),
+    });
+
+    const fetched = await client.getRawTaskLogsAsync('universes/1/tasks/2');
+
+    expect(fetched.text).toBe('a\nb\nc\nd\ne\nf');
+    expect(fetched.stats).toEqual({
+      requests: 2,
+      pages: 2,
+      entries: 3,
+      messages: 6,
+      chars: 11,
+    });
+  });
+
+  it('counts every attempt when empty logs were retried', async () => {
+    // The retry is invisible in the text it eventually returns, so a run whose
+    // logs only showed up on the third ask looks exactly like one that answered
+    // immediately. It is the difference between a slow API and a silent run.
+    vi.spyOn(global, 'setTimeout').mockImplementation((fn: () => void) => {
+      fn();
+      return 0 as unknown as NodeJS.Timeout;
+    });
+
+    // One unpaged response per attempt: two empty, then the logs. A limiter
+    // that pages would fold all three into a single attempt and prove nothing.
+    let attempt = 0;
+    const rateLimiter = {
+      fetchAsync: vi.fn(async () => {
+        attempt++;
+        return new Response(
+          JSON.stringify({
+            luauExecutionSessionTaskLogs:
+              attempt < 3
+                ? []
+                : [
+                    {
+                      structuredMessages: [
+                        {
+                          message: 'late',
+                          createTime: '2026-08-27T00:00:00.38Z',
+                          messageType: 'OUTPUT',
+                        },
+                      ],
+                    },
+                  ],
+          }),
+          { status: 200 }
+        );
+      }),
+    } as unknown as RateLimiter;
+
+    const client = new OpenCloudClient({ apiKey: 'test-key', rateLimiter });
+
+    const fetched = await client.getRawTaskLogsAsync('universes/1/tasks/2');
+
+    expect(fetched.text).toBe('late');
+    expect(fetched.stats.requests).toBe(3);
+    expect(fetched.stats.pages).toBe(1);
+    expect(fetched.stats.messages).toBe(1);
+  });
+});

package/src/utils/open-cloud/open-cloud-client.ts

@@ -7,6 +7,30 @@ import {
   parseTestLogs,
   type ParsedTestLogs,
 } from '../testing/test-log-parser.js';
+import { type LogFetchStats } from '../testing/log-fetch-stats.js';
+
+/**
+ * One engine message, with the severity Open Cloud reported for it.
+ *
+ * A message is not a line: an error arrives with its whole traceback attached,
+ * so `message` can span several. `messageType` is OUTPUT, WARNING or ERROR.
+ */
+export interface TaskLogMessage {
+  message: string;
+  messageType?: string;
+}
+
+/** A task's log text together with what the fetch had to do to collect it. */
+export interface TaskLogFetch {
+  text: string;
+  stats: LogFetchStats;
+  /**
+   * The same output as `text`, still split into typed messages. Kept because
+   * severity is the API's to state and cannot be recovered from the joined
+   * text: a traceback's continuation lines look like ordinary output.
+   */
+  messages: TaskLogMessage[];
+}
 
 export interface LuauTask {
   path: string;
@@ -22,12 +46,38 @@ export interface LuauTask {
     | 'FAILED';
   script: string;
   timeout?: string;
-  /** Script return value (populated on COMPLETE). */
-  output?: { results?: Array<{ value?: string }> };
+  /**
+   * What the script returned, populated on COMPLETE. `results` is a flat array
+   * of the returned values — `return t, "s", 42` arrives as three entries —
+   * natively typed: Roblox serializes them itself, so a returned Lua table is
+   * real nested JSON here, not a JSON string. (Which is also why a script must
+   * not JSONEncode its result: that lands as a double-encoded string.)
+   *
+   * Absent whenever the task produced no result. A FAILED task carries no
+   * `output` at all, with no error message explaining why — and an oversize
+   * return value (~4MB observed; ~2MB still arrives complete) fails the task
+   * exactly that way rather than truncating the value.
+   */
+  output?: { results?: unknown[] };
   /** Error details (populated on FAILED). */
   error?: { code?: string; message?: string };
 }
 
+/**
+ * The values a finished task's script returned, or `undefined` when the task
+ * reported no result at all.
+ *
+ * The distinction matters: `undefined` means nothing came back to read, so a
+ * caller can fall back to the task's logs, while `[]` means the task did report
+ * a result and the script returned nothing — no fallback will find more.
+ */
+export function getTaskReturnValues(task: LuauTask): unknown[] | undefined {
+  if (!task.output) {
+    return undefined;
+  }
+  return task.output.results ?? [];
+}
+
 export interface OpenCloudClientOptions {
   apiKey: string | (() => Promise<string>);
   rateLimiter: RateLimiter;
@@ -316,22 +366,32 @@ export class OpenCloudClient {
 
   async getTaskLogsAsync(taskPath: string): Promise<ParsedTestLogs> {
     const raw = await this.getRawTaskLogsAsync(taskPath);
-    return parseTestLogs(raw);
+    return parseTestLogs(raw.text);
   }
 
   /**
-   * Fetch raw log text from a completed Luau execution task.
+   * Fetch raw log text from a completed Luau execution task, along with the
+   * shape of the fetch that produced it.
+   *
    * Retries a few times if the API returns empty logs, since the test runner
-   * always produces at least some output.
+   * always produces at least some output. The reported `requests` count spans
+   * every attempt, so a fetch that only filled in on its third try says so.
    */
-  async getRawTaskLogsAsync(taskPath: string): Promise<string> {
+  async getRawTaskLogsAsync(taskPath: string): Promise<TaskLogFetch> {
     const maxAttempts = 3;
     const retryDelayMs = 1000;
+    let requests = 0;
 
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      const logs = await this._fetchRawLogsAsync(taskPath);
-      if (logs || attempt === maxAttempts) {
-        return logs;
+      const fetched = await this._fetchRawLogsAsync(taskPath);
+      requests += fetched.stats.requests;
+
+      if (fetched.text || attempt === maxAttempts) {
+        return {
+          text: fetched.text,
+          stats: { ...fetched.stats, requests },
+          messages: fetched.messages,
+        };
       }
       await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
     }
@@ -340,12 +400,12 @@ export class OpenCloudClient {
     return this._fetchRawLogsAsync(taskPath);
   }
 
-  private async _fetchRawLogsAsync(taskPath: string): Promise<string> {
+  private async _fetchRawLogsAsync(taskPath: string): Promise<TaskLogFetch> {
     const apiKey = await this._resolveApiKeyAsync();
     // Arrival order, deliberately. Do not sort by createTime: every print in a
     // single frame shares one value, so it cannot order them anyway, and the
     // fractional digit count varies, so comparing the strings reorders them.
-    const messages: string[] = [];
+    const messages: TaskLogMessage[] = [];
     let pageToken: string | undefined;
     let pagesFetched = 0;
     let entriesFetched = 0;
@@ -383,9 +443,16 @@ export class OpenCloudClient {
 
       for (const entry of data.luauExecutionSessionTaskLogs ?? []) {
         if (entry.structuredMessages?.length) {
-          messages.push(...entry.structuredMessages.map((msg) => msg.message));
+          messages.push(
+            ...entry.structuredMessages.map((msg) => ({
+              message: msg.message,
+              messageType: msg.messageType,
+            }))
+          );
         } else if (entry.messages?.length) {
-          messages.push(...entry.messages);
+          // The flat view carries no severity, which stays absent rather than
+          // being guessed at.
+          messages.push(...entry.messages.map((message) => ({ message })));
         }
       }
 
@@ -394,17 +461,26 @@ export class OpenCloudClient {
       pageToken = data.nextPageToken || undefined;
     } while (pageToken);
 
-    const text = messages.join('\n');
+    const text = messages.map((entry) => entry.message).join('\n');
+
+    const stats: LogFetchStats = {
+      requests: pagesFetched,
+      pages: pagesFetched,
+      entries: entriesFetched,
+      messages: messages.length,
+      chars: text.length,
+    };
 
     // Log volume is the prime suspect when engine output goes missing between
     // the task and the parser, and the parser cannot tell a short run from a
-    // truncated fetch. Record what arrived so a real run can settle it.
+    // truncated fetch. Handed out with the text rather than only printed, so
+    // the diagnostic that finds the output missing can say what the fetch saw.
     OutputHelper.verbose(
-      `[open-cloud] Task logs: ${pagesFetched} page(s), ${entriesFetched} entries, ` +
-        `${messages.length} messages, ${text.length} chars`
+      `[open-cloud] Task logs: ${stats.pages} page(s), ${stats.entries} entries, ` +
+        `${stats.messages} messages, ${stats.chars} chars`
     );
 
-    return text;
+    return { text, stats, messages };
   }
 
   /**