start-command 0.30.5 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # start-command
 
+## 0.31.0
+
+### Minor Changes
+
+- b14f11c: Add `--network` and repeatable `--network-alias` options for Docker-isolated commands.
+
 ## 0.30.5
 
 ### Patch Changes

package/package.json

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

package/src/bin/cli.js

@@ -581,10 +581,7 @@ async function runWithIsolation(
       alwaysCleanupContainer: options.alwaysCleanupContainer,
       keepContainer: options.keepContainer,
       keepContainerOnFail: options.keepContainerOnFail,
-      volumes: options.volumes,
-      mounts: options.mounts,
-      env: options.env,
-      privileged: options.privileged,
+      ...buildDockerRuntimeMetadata(options),
       shell: options.shell,
       logPath: logFilePath,
     });

package/src/lib/args-parser.js

@@ -15,6 +15,8 @@
  * --mount <mount-spec>             Docker --mount spec (repeatable, docker only)
  * --env, -e <KEY=VALUE>            Environment variable for docker container (repeatable, docker only)
  * --privileged                     Run docker container in privileged mode (docker only)
+ * --network <name>                 Connect docker container to a named network (docker only)
+ * --network-alias <alias>          Add a network-scoped alias (repeatable, docker only)
  * --endpoint <endpoint>            SSH endpoint (required for ssh isolation, e.g., user@host)
  * --isolated-user, -u [username]   Create isolated user with same permissions (auto-generated name if not specified)
  * --keep-user                      Keep isolated user after command completes (don't delete)
@@ -37,6 +39,7 @@
  */
 
 const { getDefaultDockerImage } = require('./docker-utils');
+const dockerNetworkOptions = require('./docker-network-options');
 const { parseSequence, isSequence } = require('./sequence-parser');
 
 // Debug mode from environment
@@ -178,6 +181,8 @@ function parseArgs(args) {
     mounts: [], // Docker --mount specs, applied to docker levels
     env: [], // Docker environment variables (-e/--env, KEY=VALUE), applied to docker levels
     privileged: false, // Run docker container in privileged mode
+    network: null, // Docker network name
+    networkAliases: [], // Docker network-scoped aliases
     endpoint: null, // SSH endpoint (current level, e.g., user@host)
     endpointStack: null, // SSH endpoints for each level (with nulls for non-ssh levels)
     user: false, // Create isolated user
@@ -396,6 +401,11 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  const networkOption = dockerNetworkOptions.parse(args, index, options);
+  if (networkOption) {
+    return networkOption;
+  }
+
   // --endpoint (for ssh) - supports sequence for stacked isolation
   if (arg === '--endpoint') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
@@ -645,8 +655,7 @@ function parseOption(args, index, options) {
 }
 
 /**
- * Throw if docker runtime options (--volume, --mount, --env, --privileged)
- * are present but the isolation configuration does not include docker.
+ * Throw if docker runtime options are present without docker isolation.
  * @param {object} options - Parsed options
  * @throws {Error} If a docker-only option is set without docker isolation
  */
@@ -671,6 +680,7 @@ function validateDockerRuntimeOptionsRequireDocker(options) {
       '--privileged option is only valid when isolation stack includes docker'
     );
   }
+  dockerNetworkOptions.validateRequireDocker(options);
 }
 
 function validateDockerCleanupOptions(options, hasDocker) {

package/src/lib/docker-cleanup.js

@@ -109,6 +109,22 @@ function readDockerContainerOomKilled(containerName) {
   return null;
 }
 
+function readDockerContainerStatus(containerName) {
+  const result = spawnSync(
+    getDockerCommand(),
+    ['inspect', '-f', '{{.State.Status}}', containerName],
+    getDockerSpawnOptions({
+      encoding: 'utf8',
+      env: process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+  );
+  if (result.error || result.status !== 0) {
+    return null;
+  }
+  return String(result.stdout || '').trim() || null;
+}
+
 function removeDockerContainer(containerName, logPath = null) {
   const result = spawnSync(
     getDockerCommand(),
@@ -237,6 +253,7 @@ module.exports = {
   getDockerContainerCleanupInstructions,
   appendDockerContainerCleanupPolicyMessage,
   readDockerContainerOomKilled,
+  readDockerContainerStatus,
   removeDockerContainer,
   buildDetachedDockerCompletionScript,
   startDetachedDockerCompletionWatcher,

package/src/lib/docker-network-options.js

@@ -0,0 +1,44 @@
+/** Parse and validate Docker network wrapper options. */
+
+function parseDockerNetworkOption(args, index, options) {
+  const arg = args[index];
+  if (arg === '--network' || arg === '--network-alias') {
+    if (index + 1 >= args.length || args[index + 1].startsWith('-')) {
+      const value = arg === '--network' ? 'network name' : 'alias';
+      throw new Error(`Option ${arg} requires a ${value} argument`);
+    }
+    if (arg === '--network') {
+      options.network = args[index + 1];
+    } else {
+      options.networkAliases.push(args[index + 1]);
+    }
+    return 2;
+  }
+  if (arg.startsWith('--network=')) {
+    options.network = arg.slice('--network='.length);
+    return 1;
+  }
+  if (arg.startsWith('--network-alias=')) {
+    options.networkAliases.push(arg.slice('--network-alias='.length));
+    return 1;
+  }
+  return 0;
+}
+
+function validateDockerNetworkOptionsRequireDocker(options) {
+  if (options.network) {
+    throw new Error(
+      '--network option is only valid when isolation stack includes docker'
+    );
+  }
+  if (options.networkAliases?.length > 0) {
+    throw new Error(
+      '--network-alias option is only valid when isolation stack includes docker'
+    );
+  }
+}
+
+module.exports = {
+  parse: parseDockerNetworkOption,
+  validateRequireDocker: validateDockerNetworkOptionsRequireDocker,
+};

package/src/lib/isolation.js

@@ -28,6 +28,7 @@ const {
   getDockerContainerCleanupInstructions,
   appendDockerContainerCleanupPolicyMessage,
   readDockerContainerOomKilled,
+  readDockerContainerStatus,
   removeDockerContainer,
   startDetachedDockerCompletionWatcher,
   spawnAttachedDocker,
@@ -499,9 +500,9 @@ const {
 /**
  * Build the docker run runtime argument list contributed by configurable
  * container options: privileged mode, environment variables, volumes/bind
- * mounts, and --mount specs. Returned in a stable order so they can be spliced
+ * mounts, --mount specs, and network configuration. Returned in a stable order so they can be spliced
  * into the `docker run` argv before the image name.
- * @param {object} options - Options (privileged, env, volumes, mounts)
+ * @param {object} options - Options (privileged, env, volumes, mounts, network, networkAliases)
  * @returns {string[]} Docker CLI arguments
  */
 function buildDockerRuntimeArgs(options = {}) {
@@ -518,6 +519,12 @@ function buildDockerRuntimeArgs(options = {}) {
   for (const mount of options.mounts || []) {
     args.push('--mount', mount);
   }
+  if (options.network) {
+    args.push('--network', options.network);
+  }
+  for (const alias of options.networkAliases || []) {
+    args.push('--network-alias', alias);
+  }
   return args;
 }
 
@@ -542,6 +549,14 @@ function buildDockerRuntimeStatusLines(options = {}) {
   if (options.privileged) {
     lines.push(`[Isolation] Privileged: true`);
   }
+  if (options.network) {
+    lines.push(`[Isolation] Network: ${options.network}`);
+  }
+  if (options.networkAliases && options.networkAliases.length > 0) {
+    lines.push(
+      `[Isolation] Network aliases: ${options.networkAliases.join(', ')}`
+    );
+  }
   return lines;
 }
 
@@ -549,7 +564,7 @@ function buildDockerRuntimeStatusLines(options = {}) {
  * Build the execution-record metadata for docker runtime options, normalizing
  * empty collections and a falsy privileged flag to `null`.
  * @param {object} options - Options (volumes, mounts, env, privileged)
- * @returns {{volumes: ?string[], mounts: ?string[], env: ?string[], privileged: ?boolean}}
+ * @returns {{volumes: ?string[], mounts: ?string[], env: ?string[], privileged: ?boolean, network: ?string, networkAliases: ?string[]}}
  */
 function buildDockerRuntimeMetadata(options = {}) {
   return {
@@ -558,6 +573,11 @@ function buildDockerRuntimeMetadata(options = {}) {
     mounts: options.mounts && options.mounts.length > 0 ? options.mounts : null,
     env: options.env && options.env.length > 0 ? options.env : null,
     privileged: options.privileged || null,
+    network: options.network || null,
+    networkAliases:
+      options.networkAliases && options.networkAliases.length > 0
+        ? options.networkAliases
+        : null,
   };
 }
 
@@ -597,6 +617,8 @@ function runInDocker(command, options = {}) {
   }
 
   const containerName = options.session || generateSessionName('docker');
+  const containerExistedBeforeLaunch =
+    readDockerContainerStatus(containerName) !== null;
   const cleanupPolicy = getDockerContainerCleanupPolicy(options);
   if (!dockerImageExists(options.image)) {
     // Pass logPath so the image-preparation phase (docker pull) is recorded in
@@ -671,6 +693,12 @@ function runInDocker(command, options = {}) {
           dockerResult.stderr.trim() ||
           dockerResult.stdout.trim() ||
           `docker exited with code ${dockerResult.status}`;
+        if (
+          !containerExistedBeforeLaunch &&
+          readDockerContainerStatus(containerName) === 'created'
+        ) {
+          removeDockerContainer(containerName, options.logPath);
+        }
         throw new Error(dockerError);
       }
 
@@ -760,8 +788,17 @@ function runInDocker(command, options = {}) {
           }
 
           const oomKilled = readDockerContainerOomKilled(containerName);
+          const launchFailed =
+            !containerExistedBeforeLaunch &&
+            readDockerContainerStatus(containerName) === 'created';
 
-          if (
+          if (launchFailed) {
+            if (removeDockerContainer(containerName, options.logPath)) {
+              message += `\nContainer removed after launch failure.`;
+            } else {
+              message += `\nWarning: failed to remove container after launch failure.`;
+            }
+          } else if (
             shouldCleanupDockerContainer(cleanupPolicy, exitCode, oomKilled)
           ) {
             if (removeDockerContainer(containerName, options.logPath)) {

package/src/lib/usage.js

@@ -14,6 +14,8 @@ Options:
   --mount <spec>        Docker --mount spec (repeatable, docker only)
   --env, -e <KEY=VALUE> Environment variable for docker container (repeatable, docker only)
   --privileged          Run docker container in privileged mode (docker only)
+  --network <name>      Connect docker container to a named network (docker only)
+  --network-alias <alias> Add network-scoped alias (repeatable, docker only)
   --endpoint <endpoint> SSH endpoint (required for ssh isolation, e.g., user@host)
   --isolated-user, -u [name]  Create isolated user with same permissions
   --keep-user           Keep isolated user after command completes

package/test/docker-network-integration.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env bun
+/** Real-daemon integration coverage for Docker network isolation (issue #154). */
+
+const { after, before, describe, it } = require('node:test');
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const { randomUUID } = require('crypto');
+const { runInDocker } = require('../src/lib/isolation');
+
+const suffix = randomUUID().slice(0, 8);
+const network = `start-network-${suffix}`;
+const sidecar = `start-sidecar-${suffix}`;
+const connected = `start-connected-${suffix}`;
+const control = `start-control-${suffix}`;
+const missing = `start-missing-${suffix}`;
+const missingAttached = `start-missing-attached-${suffix}`;
+let dockerAvailable = false;
+
+function docker(args) {
+  return spawnSync('docker', args, { encoding: 'utf8' });
+}
+
+describe('Docker named network integration', { timeout: 60000 }, () => {
+  before(() => {
+    dockerAvailable =
+      process.platform === 'linux' && docker(['info']).status === 0;
+    if (!dockerAvailable) {
+      return;
+    }
+
+    const created = docker(['network', 'create', '--internal', network]);
+    assert.strictEqual(created.status, 0, created.stderr);
+    const started = docker([
+      'run',
+      '-d',
+      '--name',
+      sidecar,
+      '--network',
+      network,
+      '--network-alias',
+      'formal-ai',
+      'alpine:3.23',
+      'sleep',
+      '60',
+    ]);
+    assert.strictEqual(started.status, 0, started.stderr);
+  });
+
+  after(() => {
+    if (!dockerAvailable) {
+      return;
+    }
+    docker(['rm', '-f', sidecar, connected, control, missing, missingAttached]);
+    docker(['network', 'rm', network]);
+  });
+
+  it('resolves an alias only from containers joined to the internal network', async () => {
+    if (!dockerAvailable) {
+      return;
+    }
+
+    const joined = await runInDocker('ping -c 1 formal-ai', {
+      image: 'alpine:3.23',
+      session: connected,
+      network,
+      networkAliases: ['task'],
+      detached: true,
+      shell: 'sh',
+      keepContainer: true,
+    });
+    assert.strictEqual(joined.success, true, joined.message);
+    const joinedExit = docker(['wait', connected]);
+    assert.strictEqual(joinedExit.status, 0, joinedExit.stderr);
+    assert.strictEqual(joinedExit.stdout.trim(), '0');
+
+    const unconnected = await runInDocker('ping -c 1 formal-ai', {
+      image: 'alpine:3.23',
+      session: control,
+      shell: 'sh',
+      alwaysCleanupContainer: true,
+    });
+    assert.strictEqual(unconnected.success, false);
+  });
+
+  it('fails for a missing network without orphaning a container', async () => {
+    if (!dockerAvailable) {
+      return;
+    }
+
+    const result = await runInDocker('echo should-not-run', {
+      image: 'alpine:3.23',
+      session: missing,
+      network: `${network}-absent`,
+      detached: true,
+      shell: 'sh',
+    });
+    assert.strictEqual(result.success, false);
+    assert.match(result.message, /network .* not found/i);
+    assert.notStrictEqual(docker(['inspect', missing]).status, 0);
+
+    const attachedResult = await runInDocker('echo should-not-run', {
+      image: 'alpine:3.23',
+      session: missingAttached,
+      network: `${network}-absent`,
+      shell: 'sh',
+    });
+    assert.strictEqual(attachedResult.success, false);
+    assert.notStrictEqual(docker(['inspect', missingAttached]).status, 0);
+
+    const conflict = await runInDocker('echo should-not-run', {
+      image: 'alpine:3.23',
+      session: sidecar,
+      network: `${network}-absent`,
+      detached: true,
+      shell: 'sh',
+    });
+    assert.strictEqual(conflict.success, false);
+    assert.strictEqual(docker(['inspect', sidecar]).status, 0);
+  });
+});

package/test/docker-runtime-options.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 /**
- * Tests for Docker runtime options: --volume/-v, --mount, --env/-e, --privileged
+ * Tests for Docker runtime options: --volume/-v, --mount, --env/-e,
+ * --privileged, --network, and --network-alias
  *
  * Reproduces issue #132: callers need to configure bind mounts, volumes,
  * environment variables, and privileged mode for the docker isolation backend
@@ -90,12 +91,58 @@ describe('Docker runtime options parsing', () => {
     assert.strictEqual(result.wrapperOptions.privileged, true);
   });
 
+  it('should parse --network value and equals forms without consuming child args', () => {
+    const spaced = parseArgs([
+      '-i',
+      'docker',
+      '--network',
+      'hive-formal-ai',
+      '--',
+      '--network',
+      'child-network',
+    ]);
+    const equals = parseArgs([
+      '-i',
+      'docker',
+      '--network=hive-formal-ai',
+      '--',
+      'echo',
+      'ok',
+    ]);
+
+    assert.strictEqual(spaced.wrapperOptions.network, 'hive-formal-ai');
+    assert.deepStrictEqual(spaced.rawCommand, ['--network', 'child-network']);
+    assert.strictEqual(equals.wrapperOptions.network, 'hive-formal-ai');
+  });
+
+  it('should parse repeatable --network-alias value and equals forms', () => {
+    const result = parseArgs([
+      '-i',
+      'docker',
+      '--network',
+      'hive-formal-ai',
+      '--network-alias',
+      'formal-ai',
+      '--network-alias=checker',
+      '--',
+      'echo',
+      'ok',
+    ]);
+
+    assert.deepStrictEqual(result.wrapperOptions.networkAliases, [
+      'formal-ai',
+      'checker',
+    ]);
+  });
+
   it('should default runtime options to empty/false', () => {
     const result = parseArgs(['-i', 'docker', '--', 'ls']);
     assert.deepStrictEqual(result.wrapperOptions.volumes, []);
     assert.deepStrictEqual(result.wrapperOptions.mounts, []);
     assert.deepStrictEqual(result.wrapperOptions.env, []);
     assert.strictEqual(result.wrapperOptions.privileged, false);
+    assert.strictEqual(result.wrapperOptions.network, null);
+    assert.deepStrictEqual(result.wrapperOptions.networkAliases, []);
   });
 
   it('should throw when --volume requires an argument', () => {
@@ -136,6 +183,15 @@ describe('Docker runtime options validation', () => {
     }, /--privileged option is only valid when isolation stack includes docker/);
   });
 
+  it('should reject network options without docker', () => {
+    assert.throws(() => {
+      parseArgs(['-i', 'tmux', '--network', 'private', '--', 'ls']);
+    }, /--network option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs(['--network-alias', 'service', '--', 'ls']);
+    }, /--network-alias option is only valid when isolation stack includes docker/);
+  });
+
   it('should accept runtime options when stack includes docker', () => {
     const result = parseArgs([
       '-i',
@@ -171,6 +227,8 @@ describe('buildDockerRuntimeArgs', () => {
       env: ['FOO=bar', 'GH_TOKEN=secret'],
       volumes: ['/h/a:/c/a', '/h/b:/c/b:ro'],
       mounts: ['type=bind,src=/h,dst=/c'],
+      network: 'hive-formal-ai',
+      networkAliases: ['formal-ai', 'checker'],
     });
     assert.deepStrictEqual(args, [
       '--privileged',
@@ -184,6 +242,12 @@ describe('buildDockerRuntimeArgs', () => {
       '/h/b:/c/b:ro',
       '--mount',
       'type=bind,src=/h,dst=/c',
+      '--network',
+      'hive-formal-ai',
+      '--network-alias',
+      'formal-ai',
+      '--network-alias',
+      'checker',
     ]);
   });
 });
@@ -199,12 +263,16 @@ describe('buildDockerRuntimeStatusLines', () => {
       mounts: ['type=bind,src=/h,dst=/c'],
       env: ['FOO=bar'],
       privileged: true,
+      network: 'hive-formal-ai',
+      networkAliases: ['formal-ai', 'checker'],
     });
     assert.deepStrictEqual(lines, [
       '[Isolation] Volumes: /h:/c:ro',
       '[Isolation] Mounts: type=bind,src=/h,dst=/c',
       '[Isolation] Env: FOO=bar',
       '[Isolation] Privileged: true',
+      '[Isolation] Network: hive-formal-ai',
+      '[Isolation] Network aliases: formal-ai, checker',
     ]);
   });
 
@@ -223,6 +291,8 @@ describe('buildDockerRuntimeMetadata', () => {
       mounts: null,
       env: null,
       privileged: null,
+      network: null,
+      networkAliases: null,
     });
   });
 
@@ -233,12 +303,16 @@ describe('buildDockerRuntimeMetadata', () => {
         mounts: ['type=bind,src=/h,dst=/c'],
         env: ['FOO=bar'],
         privileged: true,
+        network: 'hive-formal-ai',
+        networkAliases: ['formal-ai', 'checker'],
       }),
       {
         volumes: ['/h:/c'],
         mounts: ['type=bind,src=/h,dst=/c'],
         env: ['FOO=bar'],
         privileged: true,
+        network: 'hive-formal-ai',
+        networkAliases: ['formal-ai', 'checker'],
       }
     );
   });