start-command 0.29.1 → 0.29.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # start-command
 
+## 0.29.2
+
+### Patch Changes
+
+- 8518034: Record the docker image-preparation phase in the session log (issue #138). When a `--isolated docker` run needs to `docker pull` an image, the pull output is now teed into the session-log file (`/tmp/start-command/logs/isolation/docker/<uuid>.log`) in real time and bracketed with `Preparing image <name>…` / `Image ready (<duration>)` markers (or `Image preparation failed` on error). Previously the minutes spent pulling a (potentially multi-GB) image left no trace in the log, so operators tailing `$ --upload-log <uuid>` during startup saw only the header. The single session-log file is now a gap-free record of the run, including the longest, most failure-prone phase.
+
 ## 0.29.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.29.1",
+  "version": "0.29.2",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {

package/src/lib/docker-utils.js

@@ -7,6 +7,8 @@
  */
 
 const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const { execSync, spawnSync } = require('child_process');
 
 /**
@@ -102,31 +104,141 @@ function dockerImageExists(image) {
   }
 }
 
+/**
+ * Run `docker pull <image>` while teeing its output to the session log file.
+ *
+ * When a logPath is given (and tee is available, i.e. non-Windows), the pull
+ * output is streamed to BOTH the console and the log file in real time so the
+ * image-preparation phase is captured in the single session log (issue #138).
+ * docker's own exit code is recovered via a sentinel status file because the
+ * exit status of a `cmd | tee` pipeline reflects tee, not docker.
+ *
+ * Without a logPath, it falls back to the previous behavior: inherited stdio
+ * for real-time console output, with no log capture. On Windows (no portable
+ * shell `tee`) but with a logPath, the pull output is captured, echoed to the
+ * console, and appended to the log after the pull so the session log still
+ * records the image-preparation phase (issue #138) — just not streamed live.
+ *
+ * @param {string} image - Docker image to pull
+ * @param {string|null} logPath - Session log file to append pull output to
+ * @returns {{status: number, error?: Error}} Spawn result (status = docker exit code)
+ */
+function runDockerPull(image, logPath) {
+  const { shellQuote } = require('./isolation-log-utils');
+
+  // Without a log target, keep the original inherited-stdio behavior for
+  // fancy real-time console output.
+  if (!logPath) {
+    return spawnSync('docker', ['pull', image], {
+      stdio: ['pipe', 'inherit', 'inherit'],
+    });
+  }
+
+  // Windows has no portable shell `tee`, so capture the pull output, echo it to
+  // the console, and append it to the log so the image-preparation phase is
+  // still recorded in the session log (issue #138), just not streamed live.
+  if (process.platform === 'win32') {
+    const { appendLogFile } = require('./isolation-log-utils');
+    const result = spawnSync('docker', ['pull', image], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+    const combined = `${result.stdout || ''}${result.stderr || ''}`;
+    if (combined) {
+      process.stdout.write(combined);
+      try {
+        appendLogFile(
+          logPath,
+          combined.endsWith('\n') ? combined : `${combined}\n`
+        );
+      } catch {
+        // best-effort: log capture must never break the pull
+      }
+    }
+    return result;
+  }
+
+  // Tee docker pull output to both the console and the log file. docker writes
+  // to a pipe here, so it emits plain progress lines (ideal for a log). The
+  // sentinel file captures docker's real exit code (the pipeline's own exit
+  // status would be tee's).
+  const statusFile = path.join(
+    os.tmpdir(),
+    `start-docker-pull-${process.pid}-${Date.now()}.status`
+  );
+  try {
+    const pipeline =
+      `{ docker pull ${shellQuote(image)} 2>&1; echo $? > ${shellQuote(statusFile)}; } ` +
+      `| tee -a ${shellQuote(logPath)}`;
+    const result = spawnSync('sh', ['-c', pipeline], {
+      stdio: ['pipe', 'inherit', 'inherit'],
+    });
+    if (result.error) {
+      return result;
+    }
+    let status = result.status;
+    try {
+      const recorded = fs.readFileSync(statusFile, 'utf8').trim();
+      if (recorded !== '') {
+        status = parseInt(recorded, 10);
+      }
+    } catch {
+      // Sentinel missing (e.g. sh/tee failed before docker ran); keep pipeline status.
+    }
+    return { ...result, status };
+  } finally {
+    try {
+      fs.unlinkSync(statusFile);
+    } catch {
+      // best-effort cleanup
+    }
+  }
+}
+
 /**
  * Pull a Docker image with output streaming
- * Displays the pull operation as a virtual command in the timeline
+ * Displays the pull operation as a virtual command in the timeline.
+ *
+ * When a logPath is provided, the image-preparation phase (the `docker pull`)
+ * is also recorded in the session log so the single log file is a gap-free
+ * record of everything that ran (issue #138): a `Preparing image …` marker with
+ * a timestamp is written before the pull, the pull output is teed into the log,
+ * and an `Image ready (<duration>)` marker is written afterwards.
+ *
  * @param {string} image - Docker image to pull
+ * @param {string|null} logPath - Optional session log file to append output to
  * @returns {{success: boolean, output: string}} Pull result
  */
-function dockerPullImage(image) {
+function dockerPullImage(image, logPath = null) {
   const {
     createVirtualCommandBlock,
     createVirtualCommandResult,
     createTimelineSeparator,
   } = require('./output-blocks');
+  const { appendLogFile, getTimestamp } = require('./isolation-log-utils');
 
   // Print the virtual command line followed by empty line for visual separation
   console.log(createVirtualCommandBlock(`docker pull ${image}`));
   console.log();
 
+  // Record the start of the image-preparation phase in the session log so
+  // operators tailing the log see progress instead of a header-only file.
+  const prepStartMs = Date.now();
+  if (logPath) {
+    appendLogFile(
+      logPath,
+      `$ docker pull ${image}\nPreparing image ${image}… (${getTimestamp()})\n`
+    );
+  }
+
   let output = '';
   let success;
 
   try {
-    // Run docker pull with inherited stdio for real-time output
-    const result = spawnSync('docker', ['pull', image], {
-      stdio: ['pipe', 'inherit', 'inherit'],
-    });
+    const result = runDockerPull(image, logPath);
+    if (result.error) {
+      throw result.error;
+    }
 
     success = result.status === 0;
 
@@ -140,6 +252,21 @@ function dockerPullImage(image) {
     console.error(`Failed to run docker pull: ${err.message}`);
     output = err.message;
     success = false;
+    if (logPath) {
+      appendLogFile(logPath, `Failed to run docker pull: ${err.message}\n`);
+    }
+  }
+
+  // Record the end of the image-preparation phase with elapsed duration so the
+  // prep time is visible even when full progress is unavailable (issue #138).
+  if (logPath) {
+    const durationSec = ((Date.now() - prepStartMs) / 1000).toFixed(1);
+    appendLogFile(
+      logPath,
+      success
+        ? `Image ready (${durationSec}s)\n`
+        : `Image preparation failed (${durationSec}s)\n`
+    );
   }
 
   // Print empty line before result marker for visual separation (issue #73)

package/src/lib/isolation.js

@@ -588,7 +588,9 @@ function runInDocker(command, options = {}) {
 
   const containerName = options.session || generateSessionName('docker');
   if (!dockerImageExists(options.image)) {
-    const pullResult = dockerPullImage(options.image);
+    // Pass logPath so the image-preparation phase (docker pull) is recorded in
+    // the session log, keeping it a gap-free record of the run (issue #138).
+    const pullResult = dockerPullImage(options.image, options.logPath);
     if (!pullResult.success) {
       return Promise.resolve({
         success: false,

package/test/regression-138.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env bun
+/**
+ * Regression tests for issue #138:
+ * "Detached docker session log omits the image-preparation phase
+ *  (docker pull / dind boot) — $ does not preserve the full log in one file"
+ *
+ * When a command is launched with `--isolated docker`, the image-preparation
+ * phase (the `docker pull`) used to be printed to the console only and never
+ * written to the session log file. An operator tailing the session log (e.g.
+ * via `$ --upload-log <uuid>`) during a multi-GB pull would see only the
+ * header — the minutes spent pulling left no trace in the log.
+ *
+ * The fix tees the pull output into the session log and brackets it with
+ * `Preparing image …` / `Image ready (<duration>)` markers so the single
+ * session-log file is a gap-free record of everything that ran.
+ *
+ * Reference: https://github.com/link-foundation/start/issues/138
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const {
+  dockerPullImage,
+  dockerImageExists,
+  isDockerAvailable,
+} = require('../src/lib/docker-utils');
+
+function makeTempLog() {
+  const logPath = path.join(
+    os.tmpdir(),
+    `start-138-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.log`
+  );
+  fs.writeFileSync(logPath, '=== Start Command Log ===\n');
+  return logPath;
+}
+
+describe('docker pull is recorded in the session log (issue #138)', () => {
+  // Silence the virtual-command console output during these tests.
+  let originalLog;
+  let originalError;
+  beforeEach(() => {
+    originalLog = console.log;
+    originalError = console.error;
+    console.log = () => {};
+    console.error = () => {};
+  });
+  afterEach(() => {
+    console.log = originalLog;
+    console.error = originalError;
+  });
+
+  it('writes prep markers and the docker error into the log on a failed pull', () => {
+    if (!isDockerAvailable()) {
+      console.log = originalLog;
+      console.log('  Skipping: docker daemon not available');
+      return;
+    }
+
+    const logPath = makeTempLog();
+    try {
+      // An invalid reference format fails fast without any network access.
+      const result = dockerPullImage('invalid..badname', logPath);
+      const contents = fs.readFileSync(logPath, 'utf8');
+
+      assert.strictEqual(
+        result.success,
+        false,
+        'pull of invalid ref must fail'
+      );
+      assert.ok(
+        contents.includes('Preparing image invalid..badname'),
+        'log must contain the "Preparing image …" start marker'
+      );
+      assert.ok(
+        contents.includes('Image preparation failed'),
+        'log must contain the failure marker with elapsed duration'
+      );
+      // The docker error itself (teed pull output) must be in the log, not just
+      // on the console — this is the core of issue #138.
+      assert.ok(
+        contents.includes('invalid reference format'),
+        'log must capture the teed docker pull error output'
+      );
+    } finally {
+      fs.rmSync(logPath, { force: true });
+    }
+  });
+
+  it('tees real pull output and an "Image ready" marker into the log', () => {
+    if (!isDockerAvailable()) {
+      console.log = originalLog;
+      console.log('  Skipping: docker daemon not available');
+      return;
+    }
+    if (process.platform === 'win32') {
+      // Windows Docker runners pull Linux images slowly/unreliably and the
+      // capture path is exercised by the failed-pull test above; skip to avoid
+      // network-dependent timeouts. The real-pull streaming path is Unix-only.
+      console.log = originalLog;
+      console.log('  Skipping: real pull is unreliable on Windows Docker');
+      return;
+    }
+
+    // Use a tiny image and force a real pull by removing it first.
+    const image = 'hello-world:latest';
+    try {
+      require('child_process').execSync(`docker rmi ${image}`, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch {
+      // image not present locally — that's fine, the pull below still runs
+    }
+
+    const logPath = makeTempLog();
+    try {
+      const result = dockerPullImage(image, logPath);
+      if (!result.success) {
+        // No network in this environment — cannot exercise the success path.
+        console.log = originalLog;
+        console.log('  Skipping: docker pull failed (no registry access?)');
+        return;
+      }
+
+      const contents = fs.readFileSync(logPath, 'utf8');
+      assert.ok(
+        contents.includes(`Preparing image ${image}`),
+        'log must contain the "Preparing image …" start marker'
+      );
+      assert.ok(
+        /Image ready \(\d+\.\d+s\)/.test(contents),
+        'log must contain "Image ready (<duration>)" marker'
+      );
+      assert.ok(
+        contents.includes('Pulling from') ||
+          contents.includes('Status:') ||
+          contents.includes('Pull complete'),
+        'log must capture the teed docker pull progress output'
+      );
+      assert.ok(
+        dockerImageExists(image),
+        'image should exist locally after a successful pull'
+      );
+    } finally {
+      fs.rmSync(logPath, { force: true });
+    }
+  });
+
+  it('does not write prep markers when no logPath is given (backward compat)', () => {
+    if (!isDockerAvailable()) {
+      console.log = originalLog;
+      console.log('  Skipping: docker daemon not available');
+      return;
+    }
+
+    // Without a logPath, dockerPullImage must still return the {success, output}
+    // shape and must not throw. We only assert the contract here.
+    const result = dockerPullImage('invalid..badname');
+    assert.strictEqual(result.success, false);
+    assert.strictEqual(typeof result.output, 'string');
+  });
+});
+
+describe('runInDocker threads logPath into dockerPullImage (issue #138)', () => {
+  it('source passes options.logPath to dockerPullImage', () => {
+    const isolationSrc = fs.readFileSync(
+      path.join(__dirname, '../src/lib/isolation.js'),
+      'utf8'
+    );
+    assert.ok(
+      /dockerPullImage\(options\.image,\s*options\.logPath\)/.test(
+        isolationSrc
+      ),
+      'runInDocker must pass options.logPath to dockerPullImage'
+    );
+  });
+
+  it('dockerPullImage tees output and writes prep markers in source', () => {
+    const dockerUtilsSrc = fs.readFileSync(
+      path.join(__dirname, '../src/lib/docker-utils.js'),
+      'utf8'
+    );
+    assert.ok(
+      dockerUtilsSrc.includes('Preparing image'),
+      'docker-utils must write a "Preparing image …" marker'
+    );
+    assert.ok(
+      dockerUtilsSrc.includes('Image ready'),
+      'docker-utils must write an "Image ready (<duration>)" marker'
+    );
+    assert.ok(
+      dockerUtilsSrc.includes('tee -a'),
+      'docker-utils must tee docker pull output into the log file'
+    );
+  });
+});