@quenty/nevermore-cli 4.43.4 → 4.45.0

package/src/commands/deploy-command/deploy-init.ts

@@ -23,13 +23,20 @@ import {
   detectTargetNameAsync,
 } from './deploy-init-utils.js';
 
+/**
+ * Stands in for the place ID in a `--dryrun` preview. A dryrun never creates a
+ * place, so there is no real ID to render — and the preview is never written.
+ */
+const DRYRUN_PLACE_ID = '<would-be-created>';
+
 interface InitState {
   packagePath: string;
   packageName: string;
   placeName: string;
   targetName: string;
   universeId?: number;
-  placeId?: number;
+  /** Resolved place ID, or {@link DRYRUN_PLACE_ID} on a dryrun. */
+  placeId?: number | typeof DRYRUN_PLACE_ID;
   project?: string;
   scriptTemplate?: string;
   mode: 'auto' | 'interactive' | 'non-interactive';
@@ -111,9 +118,8 @@ async function resolveNonInteractive(
   }
 
   if (args.createPlace && state.universeId && !state.placeId) {
-    const cookie = await getRobloxCookieAsync();
-    state.placeId = await createPlaceInUniverseAsync(
-      cookie,
+    state.placeId = await createPlaceAsync(
+      args,
       state.universeId,
       state.placeName
     );
@@ -133,7 +139,7 @@ async function resolveInteractiveAsync(
   await promptModeAsync(state);
   await ensureUniverseIdAsync(args, state); // Resolves targetName before script prompt
   await ensureProjectAndScriptAsync(args, state);
-  await ensurePromptPlaceIdAsync(state); // This modifies the cloud, so is last
+  await ensurePromptPlaceIdAsync(args, state); // This modifies the cloud, so is last
 }
 
 function isTestTarget(state: InitState): boolean {
@@ -232,15 +238,17 @@ async function ensureUniverseIdAsync(
   state.universeId = answers.universeId ?? state.universeId;
 }
 
-async function ensurePromptPlaceIdAsync(state: InitState): Promise<void> {
+async function ensurePromptPlaceIdAsync(
+  args: DeployArgs,
+  state: InitState
+): Promise<void> {
   if (!state.universeId) {
     throw new Error('Universe ID is required to set up place ID');
   }
 
   try {
-    const cookie = await getRobloxCookieAsync();
-    state.placeId = await createPlaceInUniverseAsync(
-      cookie,
+    state.placeId = await createPlaceAsync(
+      args,
       state.universeId,
       state.placeName
     );
@@ -255,6 +263,27 @@ async function ensurePromptPlaceIdAsync(state: InitState): Promise<void> {
   }
 }
 
+/**
+ * Creates the place the target will point at. On a dryrun nothing is created
+ * and nothing is fetched — not even the cookie — so the caller gets
+ * {@link DRYRUN_PLACE_ID} to render instead.
+ */
+async function createPlaceAsync(
+  args: DeployArgs,
+  universeId: number,
+  placeName: string
+): Promise<number | typeof DRYRUN_PLACE_ID> {
+  if (args.dryrun) {
+    OutputHelper.info(
+      `[DRYRUN] Would create place '${placeName}' in universe ${universeId}`
+    );
+    return DRYRUN_PLACE_ID;
+  }
+
+  const cookie = await getRobloxCookieAsync();
+  return await createPlaceInUniverseAsync(cookie, universeId, placeName);
+}
+
 async function ensureProjectAndScriptAsync(
   args: DeployArgs,
   state: InitState
@@ -320,7 +349,8 @@ async function writeConfig(
     targets: {
       [state.targetName]: {
         universeId: state.universeId!,
-        placeId: state.placeId!,
+        // On a dryrun this is DRYRUN_PLACE_ID, which only ever gets printed.
+        placeId: state.placeId as number,
         project: state.project!.replace(/\\/g, '/'),
         ...(state.scriptTemplate
           ? { scriptTemplate: state.scriptTemplate.replace(/\\/g, '/') }
@@ -332,7 +362,7 @@ async function writeConfig(
   const configJson = JSON.stringify(config, null, 2);
 
   if (args.dryrun) {
-    OutputHelper.info('[DRYRUN]: Would write deploy.nevermore.json:');
+    OutputHelper.info('[DRYRUN] Would write deploy.nevermore.json:');
     console.log(configJson);
     return;
   }

package/src/commands/deploy-command/index.ts

@@ -559,7 +559,7 @@ export class DeployCommand<T> implements CommandModule<T, DeployArgs> {
           reporters.push(
             new GithubCommentTableReporter(
               state,
-              createDeployCommentConfig(),
+              createDeployCommentConfig(deployLabels),
               isMultiPlace ? MULTI_PLACE_CONCURRENCY : 1
             )
           );

package/src/utils/deploy/deploy-github-columns.ts

@@ -11,16 +11,26 @@ export interface BatchDeployResult extends PackageResult {
   placeId: number;
 }
 
-/** Shared config for the deploy results GitHub comment reporter. */
-export function createDeployCommentConfig(): GithubCommentTableConfig {
+/**
+ * Shared config for the deploy results GitHub comment reporter.
+ *
+ * Takes the labels rather than fixing them, because a publish and a deploy are
+ * different words and the command already knows which it is doing. Without
+ * this the comment said "Failed" for a run whose terminal output said "DEPLOY
+ * FAILED" — the same run, described two ways.
+ */
+export function createDeployCommentConfig(labels?: {
+  successLabel?: string;
+  failureLabel?: string;
+}): GithubCommentTableConfig {
   return {
     heading: 'Deploy Results',
     commentMarker: '<!-- nevermore-deploy-results -->',
     sectionId: 'deploy',
     extraColumns: [createErrorColumn(), createTryItColumn()],
     errorHeading: 'Deploy Results',
-    successLabel: 'Deployed',
-    failureLabel: 'Failed',
+    successLabel: labels?.successLabel ?? 'Deployed',
+    failureLabel: labels?.failureLabel ?? 'DEPLOY FAILED',
     summaryVerb: 'deployed',
   };
 }

package/src/utils/deploy/deploy-metadata.ts

@@ -25,7 +25,7 @@ export type DeployMetadataAttributes = Record<
 const INJECT_SCRIPT_PATH = resolvePackagePath(
   import.meta.url,
   'build-scripts',
-  'transform-inject-deploy-metadata.luau'
+  'transform-inject-deploy-metadata.lua'
 );
 
 function _git(args: string[]): string | undefined {

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

@@ -17,6 +17,7 @@ import {
   type DeployPlaceOptions,
   type RunScriptOptions,
   type ScriptRunResult,
+  type JobLogs,
 } from './job-context.js';
 import { type OpenCloudClient } from '../open-cloud/open-cloud-client.js';
 import { type BasePlaceResolver } from '@quenty/nevermore-deploy';
@@ -24,7 +25,7 @@ import { type BasePlaceResolver } from '@quenty/nevermore-deploy';
 const MERGE_SCRIPT_PATH = resolvePackagePath(
   import.meta.url,
   'build-scripts',
-  'transform-rojo-merge-place.luau'
+  'transform-rojo-merge-place.lua'
 );
 
 interface SharedRojoBuild {
@@ -300,7 +301,7 @@ export abstract class BaseJobContext implements JobContext {
     deployment: Deployment,
     options: RunScriptOptions
   ): Promise<ScriptRunResult>;
-  abstract getLogsAsync(deployment: Deployment): Promise<string>;
+  abstract getLogsAsync(deployment: Deployment): Promise<JobLogs>;
   abstract releaseAsync(deployment: Deployment): Promise<void>;
 
   async disposeAsync(): Promise<void> {

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

@@ -12,6 +12,7 @@ import {
   type JobContext,
   type RunScriptOptions,
   type ScriptRunResult,
+  type JobLogs,
 } from './job-context.js';
 import { type BuildPlaceOptions } from '../build/build.js';
 import { type BatchTarget } from '../batch/changed-packages-utils.js';
@@ -21,9 +22,15 @@ import {
   generateCombinedProjectAsync,
 } from '../testing/runner/combined-project-generator.js';
 import {
+  type BatchDiagnosticLevel,
   type BatchPackageResult,
   parseBatchTestLogs,
 } from '../testing/parsers/batch-log-parser.js';
+import { type LogFetchStats } from '../testing/log-fetch-stats.js';
+import {
+  toRenderableLines,
+  type RenderableLogLine,
+} from '../testing/parsers/batch-log-renderer.js';
 
 /** Per-package deployment handle. Wraps a shared inner deployment. */
 class BatchDeployment implements Deployment {
@@ -50,6 +57,28 @@ interface CombinedBuildState {
  * package configured with one — those belong in `nevermore batch test
  * --no-aggregated`, or in an integration deploy.
  */
+/**
+ * Everything one aggregated batch produced, as data.
+ *
+ * The execution used to parse, render and print from in here. Printing from a
+ * job context put presentation in the transport, bypassed whatever reporter the
+ * command had chosen — output written straight to the console is invisible to a
+ * SpinnerReporter's capture — and left the whole path untestable without spying
+ * on `console.log`. The context returns this instead, and the command layer
+ * decides what to show.
+ */
+export interface BatchExecutionOutcome {
+  results: Map<string, BatchPackageResult>;
+  /** The run's output, typed by severity and not yet rendered. */
+  lines: RenderableLogLine[];
+  /** What the fetch had to do to collect it; absent for a transport that cannot say. */
+  stats?: LogFetchStats;
+  /** What reading the log turned up, to report after the log itself. */
+  diagnostics: Array<{ level: BatchDiagnosticLevel; message: string }>;
+  /** Section slug to package name, for whoever titles the sections. */
+  slugToPackage: Map<string, string>;
+}
+
 export class BatchScriptJobContext implements JobContext {
   private _inner: JobContext;
   private _batchTargets: BatchTarget[];
@@ -62,7 +91,7 @@ export class BatchScriptJobContext implements JobContext {
   // Lazy-promise state
   private _combinedBuildPromise?: Promise<CombinedBuildState>;
   private _deployPromise?: Promise<Deployment>;
-  private _executionPromise?: Promise<Map<string, BatchPackageResult>>;
+  private _executionPromise?: Promise<BatchExecutionOutcome>;
 
   // State for cleanup
   private _combinedBuildContext?: BuildContext;
@@ -124,8 +153,8 @@ export class BatchScriptJobContext implements JobContext {
     options: RunScriptOptions
   ): Promise<ScriptRunResult> {
     const batchDeployment = deployment as BatchDeployment;
-    const packageResults = await this._getBatchExecutionAsync();
-    const result = packageResults.get(batchDeployment.packageName);
+    const { results } = await this._getBatchExecutionAsync();
+    const result = results.get(batchDeployment.packageName);
 
     if (!result) {
       return { success: false };
@@ -135,15 +164,39 @@ export class BatchScriptJobContext implements JobContext {
       success: result.success,
       durationMs: result.durationMs,
       errorMessage: result.error,
+      // returnValues stays absent: one execution covers every package, so
+      // nothing it returns belongs to any single one of them. The batch runner
+      // folds each package's own results into the batch summary, which the log
+      // parser has already split back out — so they are handed over decoded
+      // rather than left for the caller to find in a return value that is not
+      // this package's.
+      testResults: result.testResults,
+      logsLost: result.logsLost,
     };
   }
 
-  async getLogsAsync(deployment: Deployment): Promise<string> {
-    const batchDeployment = deployment as BatchDeployment;
-    const packageResults = await this._getBatchExecutionAsync();
-    const result = packageResults.get(batchDeployment.packageName);
+  /**
+   * Run the batch if it has not run, and hand back everything it produced.
+   *
+   * Public so the command layer can render the run once, before the
+   * per-package loop asks for results — which is also what keeps the shared
+   * build and upload out of any one package's async context.
+   */
+  async getExecutionOutcomeAsync(): Promise<BatchExecutionOutcome> {
+    return this._getBatchExecutionAsync();
+  }
 
-    return result?.logs ?? '';
+  async getLogsAsync(deployment: Deployment): Promise<JobLogs> {
+    const batchDeployment = deployment as BatchDeployment;
+    const { results, stats } = await this._getBatchExecutionAsync();
+    const result = results.get(batchDeployment.packageName);
+
+    // The text is this package's section; the stats describe the one fetch that
+    // pulled every section, which is what happened to any package whose own
+    // section went missing from it. Messages stay empty: severity is per
+    // message across the whole window, and slicing it per package would need
+    // the section boundaries the parser already resolved.
+    return { text: result?.logs ?? '', messages: [], stats };
   }
 
   async releaseAsync(_deployment: Deployment): Promise<void> {
@@ -257,7 +310,7 @@ export class BatchScriptJobContext implements JobContext {
     return deployment;
   }
 
-  private _getBatchExecutionAsync(): Promise<Map<string, BatchPackageResult>> {
+  private _getBatchExecutionAsync(): Promise<BatchExecutionOutcome> {
     if (!this._executionPromise) {
       this._executionPromise = this._doBatchExecutionAsync();
       // On rejection, clear the promise so that a retry re-triggers the batch
@@ -268,9 +321,7 @@ export class BatchScriptJobContext implements JobContext {
     return this._executionPromise;
   }
 
-  private async _doBatchExecutionAsync(): Promise<
-    Map<string, BatchPackageResult>
-  > {
+  private async _doBatchExecutionAsync(): Promise<BatchExecutionOutcome> {
     const buildState = await this._getCombinedBuildAsync();
     const deployment = await this._getSharedDeploymentAsync();
     const { slugMap } = buildState.combinedResult;
@@ -278,7 +329,7 @@ export class BatchScriptJobContext implements JobContext {
     // Build the batch Luau script from the template
     const templatePath = resolveTemplatePath(
       import.meta.url,
-      'batch-test-runner.luau'
+      'batch-test-runner.lua'
     );
     const template = await fs.readFile(templatePath, 'utf-8');
 
@@ -300,8 +351,9 @@ export class BatchScriptJobContext implements JobContext {
       timeoutMs: this._batchTimeoutMs,
     });
 
-    // Fetch the combined logs
-    const rawLogs = await this._inner.getLogsAsync(deployment);
+    // Fetch the combined logs, with the severity and fetch that produced them.
+    const logs = await this._inner.getLogsAsync(deployment);
+    const rawLogs = logs.text;
 
     if (!result.success) {
       const stateInfo = result.taskState ? ` (state: ${result.taskState})` : '';
@@ -319,7 +371,36 @@ export class BatchScriptJobContext implements JobContext {
       OutputHelper.verbose(`Raw batch logs:\n${rawLogs || '(empty)'}`);
     }
 
-    // Parse into per-package results
-    return parseBatchTestLogs(rawLogs, slugMap);
+    // Parse into per-package results. Diagnostics are collected rather than
+    // printed: they describe the log window, so they belong after it, and that
+    // is the caller's ordering to make.
+    const diagnostics: Array<{ level: BatchDiagnosticLevel; message: string }> =
+      [];
+    const results = parseBatchTestLogs(rawLogs, slugMap, {
+      logFetchStats: logs.stats,
+      // The batch script returns the same summary it prints. Handing both over
+      // lets the parser read the copy that cannot arrive truncated, and fall
+      // back to the printed one on a transport that carries no return channel.
+      returnValues: result.returnValues,
+      onDiagnostic: (level, message) => diagnostics.push({ level, message }),
+    });
+
+    const slugToPackage = new Map<string, string>();
+    for (const [packageName, slug] of slugMap) {
+      slugToPackage.set(slug, packageName);
+    }
+
+    // Typed messages when the transport carries severity; otherwise the joined
+    // text, which renders uncolored rather than guessed at.
+    const messages =
+      logs.messages.length > 0 ? logs.messages : [{ message: rawLogs }];
+
+    return {
+      results,
+      lines: toRenderableLines(messages),
+      stats: logs.stats,
+      diagnostics,
+      slugToPackage,
+    };
   }
 }

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

@@ -0,0 +1,112 @@
+/**
+ * Unit tests for CloudJobContext.runScriptAsync — validates what a finished
+ * Open Cloud task reports back as a ScriptRunResult, in particular that a task
+ * which produced no output stays distinguishable from one that returned nothing.
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { type Reporter } from '@quenty/cli-output-helpers/reporting';
+import { CloudJobContext } from './cloud-job-context.js';
+import {
+  type LuauTask,
+  type OpenCloudClient,
+} from '../open-cloud/open-cloud-client.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;
+}
+
+/**
+ * A client whose task completes as `completedTask`. The real deployment handle
+ * is private to the context, so the test passes the three fields runScriptAsync
+ * reads off it.
+ */
+function createContext(completedTask: Partial<LuauTask>) {
+  const task = {
+    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',
+    ...completedTask,
+  } as LuauTask;
+
+  const client = {
+    createExecutionTaskAsync: vi.fn(async () => task),
+    pollTaskCompletionAsync: vi.fn(async () => task),
+  } as unknown as OpenCloudClient;
+
+  const context = new CloudJobContext(createReporter(), client);
+  const deployment = {
+    universeId: 1,
+    placeId: 2,
+    version: 3,
+  } as unknown as Deployment;
+
+  return { context, deployment };
+}
+
+describe('CloudJobContext.runScriptAsync', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('reports the values the script returned', async () => {
+    // Fake timers keep the client-side timeout race from leaving a live timer
+    // behind; nothing in the run itself waits on one.
+    vi.useFakeTimers();
+    const { context, deployment } = createContext({
+      state: 'COMPLETE',
+      output: { results: [{ slug: 'maid', counts: { passed: 1014 } }] },
+    });
+
+    const result = await context.runScriptAsync(deployment, {
+      scriptContent: 'return results',
+      packageName: 'maid',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.returnValues).toEqual([
+      { slug: 'maid', counts: { passed: 1014 } },
+    ]);
+  });
+
+  it('reports an empty result when the task returned nothing', async () => {
+    vi.useFakeTimers();
+    const { context, deployment } = createContext({
+      state: 'COMPLETE',
+      output: {},
+    });
+
+    const result = await context.runScriptAsync(deployment, {
+      scriptContent: 'print("hi")',
+      packageName: 'maid',
+    });
+
+    expect(result.returnValues).toEqual([]);
+  });
+
+  it('leaves returnValues absent when a failed task carried no output', async () => {
+    vi.useFakeTimers();
+    const { context, deployment } = createContext({
+      state: 'FAILED',
+      output: undefined,
+    });
+
+    const result = await context.runScriptAsync(deployment, {
+      scriptContent: 'return huge',
+      packageName: 'maid',
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.taskState).toBe('FAILED');
+    expect(result.returnValues).toBeUndefined();
+  });
+});

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

@@ -1,5 +1,6 @@
 import { type Reporter } from '@quenty/cli-output-helpers/reporting';
 import {
+  getTaskReturnValues,
   type LuauTask,
   type OpenCloudClient,
 } from '../open-cloud/open-cloud-client.js';
@@ -8,6 +9,7 @@ import { buildPlaceNameAsync, timeoutAsync } from '../nevermore-cli-utils.js';
 import {
   type Deployment,
   type DeployPlaceOptions,
+  type JobLogs,
   type RunScriptOptions,
   type ScriptRunResult,
 } from './job-context.js';
@@ -134,27 +136,31 @@ export class CloudJobContext extends BaseJobContext {
       success: completedTask.state === 'COMPLETE',
       taskState: completedTask.state,
       errorMessage,
+      returnValues: getTaskReturnValues(completedTask),
     };
   }
 
-  async getLogsAsync(deployment: Deployment): Promise<string> {
+  async getLogsAsync(deployment: Deployment): Promise<JobLogs> {
     const cloudDeployment = deployment as CloudDeployment;
 
     if (!cloudDeployment.taskPath) {
       throw new Error('No task has been run yet');
     }
 
-    const logs = await this._openCloudClient!.getRawTaskLogsAsync(
+    const fetched = await this._openCloudClient!.getRawTaskLogsAsync(
       cloudDeployment.taskPath
     );
 
     if (cloudDeployment.taskState && cloudDeployment.taskState !== 'COMPLETE') {
-      return [logs, `Task ended with state: ${cloudDeployment.taskState}`]
-        .filter(Boolean)
-        .join('\n');
+      const note = `Task ended with state: ${cloudDeployment.taskState}`;
+      return {
+        text: [fetched.text, note].filter(Boolean).join('\n'),
+        messages: [...fetched.messages, { message: note }],
+        stats: fetched.stats,
+      };
     }
 
-    return logs;
+    return fetched;
   }
 
   async releaseAsync(_deployment: Deployment): Promise<void> {

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>;