start-command 0.37.9 → 0.38.0

package/src/lib/execution-env.js

@@ -0,0 +1,120 @@
+/**
+ * START_* variables that tell a launched command which execution it belongs
+ * to (issue #230). Every backend exports the same three variables, next to
+ * the kill-recovery `START_COMMAND_RECOVERY_ATTEMPT`:
+ *
+ * - START_EXECUTION_ID: the execution UUID (`--session-id`)
+ * - START_SESSION_NAME: the isolation session/container name (`--session`);
+ *   empty for direct runs, which have no session
+ * - START_ATTEMPT: 1 for the first run, n for the n-th attempt (`--resume`,
+ *   kill recovery or `--append-attempt`), the same number `--status` shows
+ */
+const { shellQuote } = require('./isolation-log-utils');
+
+const EXECUTION_ID_ENV = 'START_EXECUTION_ID';
+const SESSION_NAME_ENV = 'START_SESSION_NAME';
+const ATTEMPT_ENV = 'START_ATTEMPT';
+
+/**
+ * Build the START_* variables for one attempt.
+ * @param {object} params - {executionId, sessionName, attempt}
+ * @returns {object} Variables in a stable order, or {} without an execution id
+ */
+function buildExecutionEnv({ executionId, sessionName, attempt } = {}) {
+  if (!executionId) {
+    return {};
+  }
+  const number = Number(attempt);
+  return {
+    [EXECUTION_ID_ENV]: String(executionId),
+    [SESSION_NAME_ENV]: sessionName ? String(sessionName) : '',
+    [ATTEMPT_ENV]: String(
+      Number.isSafeInteger(number) && number > 0 ? number : 1
+    ),
+  };
+}
+
+/**
+ * Build the variables from isolation options (`runIsolated`, `docker run`).
+ * @param {object} options - {sessionId|executionId, containerName|session, attemptNumber}
+ * @returns {object} Variables, or {}
+ */
+function executionEnvFromOptions(options = {}) {
+  return buildExecutionEnv({
+    executionId: options.sessionId || options.executionId,
+    sessionName: options.containerName || options.session,
+    attempt: options.attemptNumber,
+  });
+}
+
+/**
+ * `KEY=value` assignments, e.g. for `docker run -e`.
+ * @param {object} env - Variables
+ * @returns {string[]} Assignments
+ */
+function executionEnvAssignments(env = {}) {
+  return Object.entries(env).map(([key, value]) => `${key}=${value}`);
+}
+
+/**
+ * POSIX `export` statement for the variables, without a trailing separator.
+ * @param {object} env - Variables
+ * @returns {string} Statement, or '' when there is nothing to export
+ */
+function buildExecutionEnvExport(env = {}) {
+  const entries = Object.entries(env);
+  if (!entries.length) {
+    return '';
+  }
+  return `export ${entries
+    .map(([key, value]) => `${key}=${shellQuote(value)}`)
+    .join(' ')}`;
+}
+
+/**
+ * Prefix a shell command with the export statement. Used by the backends
+ * whose command runs through a shell that does not inherit our environment:
+ * a running tmux server, ssh, and `sudo` (which resets the environment).
+ * @param {string} command - Shell command
+ * @param {object} env - Variables
+ * @returns {string} Prefixed command
+ */
+function prefixWithExecutionEnv(command, env = {}) {
+  const statement = buildExecutionEnvExport(env);
+  return statement ? `${statement}; ${command}` : command;
+}
+
+/**
+ * Child-process environment with the variables applied.
+ * @param {object} env - Variables
+ * @param {object} [base] - Base environment (defaults to process.env)
+ * @returns {object} Environment
+ */
+function withExecutionEnv(env = {}, base = process.env) {
+  return { ...base, ...env };
+}
+
+/**
+ * True when this process was itself started by execution `executionId`, i.e.
+ * it is the next level of a stacked isolation that passes `--session-id`
+ * down (see command-builder.js).
+ * @param {string} executionId - Execution UUID
+ * @param {object} [env] - Environment to inspect
+ * @returns {boolean}
+ */
+function isNestedLaunchOf(executionId, env = process.env) {
+  return Boolean(executionId) && env[EXECUTION_ID_ENV] === executionId;
+}
+
+module.exports = {
+  EXECUTION_ID_ENV,
+  SESSION_NAME_ENV,
+  ATTEMPT_ENV,
+  buildExecutionEnv,
+  executionEnvFromOptions,
+  executionEnvAssignments,
+  buildExecutionEnvExport,
+  prefixWithExecutionEnv,
+  withExecutionEnv,
+  isNestedLaunchOf,
+};

package/src/lib/execution-identity.js

@@ -0,0 +1,180 @@
+/**
+ * Names an execution answers to (issue #231).
+ *
+ * An execution is found by its UUID, its backend session name, the session
+ * names it used before a resume (`options.sessionNameHistory`, #162), its
+ * display name (`options.name`, set by `--rename`) and its aliases
+ * (`options.aliases`, added by `--alias` and `--rename`). Aliases are kept
+ * apart from `sessionNameHistory` because that list names real backend
+ * sessions: `--cleanup` removes those containers and `--resume` derives the
+ * root session from it.
+ */
+
+function hasName(record, identifier) {
+  const options = record.options || {};
+  return (
+    options.name === identifier ||
+    (Array.isArray(options.aliases) && options.aliases.includes(identifier))
+  );
+}
+
+/**
+ * Resolve an identifier among stored records: UUID, then current session
+ * name, then earlier session names, then display name and aliases.
+ * @param {object[]} records - Stored records
+ * @param {string} identifier - Any name of the execution
+ * @returns {object|null} The record, or null
+ */
+function findRecord(records, identifier) {
+  if (identifier === null || identifier === undefined || identifier === '') {
+    return null;
+  }
+  return (
+    records.find((r) => r.uuid === identifier) ||
+    records.find((r) => r.options && r.options.sessionName === identifier) ||
+    records.find(
+      (r) =>
+        r.options &&
+        Array.isArray(r.options.sessionNameHistory) &&
+        r.options.sessionNameHistory.includes(identifier)
+    ) ||
+    records.find((r) => hasName(r, identifier)) ||
+    null
+  );
+}
+
+/**
+ * Every name the record answers to, UUID first, without duplicates.
+ * @param {object} record - Execution record
+ * @returns {string[]} Names
+ */
+function executionAliases(record) {
+  const options = record.options || {};
+  const names = [
+    record.uuid,
+    ...(options.sessionNameHistory || []),
+    options.sessionName,
+    ...(options.aliases || []),
+    options.name,
+  ].filter((name) => typeof name === 'string' && name);
+  return [...new Set(names)];
+}
+
+/** True once the record has a caller-given name (`--alias`/`--rename`). */
+function hasUserNames(record) {
+  const options = record.options || {};
+  return Boolean(options.name) || (options.aliases || []).length > 0;
+}
+
+/**
+ * Run `mutate(records)` under the store's database lock and persist the
+ * records it returns as changed.
+ * @param {object} store - ExecutionStore
+ * @param {Function} mutate - (records) => changed record, or null for none
+ * @returns {*} What `mutate` returned
+ */
+function withStoreLock(store, mutate) {
+  const { LockManager } = require('./execution-store');
+  const lock = new LockManager(store.lockFilePath);
+  if (!lock.acquire()) {
+    throw new Error('Failed to acquire lock for database write');
+  }
+  try {
+    const records = store.readLinoRecords();
+    const changed = mutate(records);
+    if (changed) {
+      store.writeLinoRecords(records);
+      if (store.useLinks) {
+        store.writeLinksRecord(changed);
+      }
+    }
+    return changed;
+  } finally {
+    lock.release();
+  }
+}
+
+function validateName(name) {
+  if (typeof name !== 'string' || !name.trim()) {
+    throw new Error('The new name must not be empty');
+  }
+  if (name.startsWith('-')) {
+    throw new Error(`Invalid name "${name}": names cannot start with "-"`);
+  }
+}
+
+/**
+ * Add a name to an execution (`$ --alias <id> <name>`) or rename it
+ * (`$ --rename <id> <name>`, which keeps the previous display name as an
+ * alias). The backend session/container keeps its name; only lookup and the
+ * displayed name change.
+ * @param {object} store - ExecutionStore
+ * @param {string} identifier - Any current name of the execution
+ * @param {string} name - Name to add
+ * @param {object} [options] - {rename: boolean}
+ * @returns {{success: boolean, output?: string, error?: string}}
+ */
+function nameExecution(store, identifier, name, options = {}) {
+  if (!store) {
+    return { success: false, error: 'Execution tracking is disabled.' };
+  }
+  try {
+    validateName(name);
+    let unchanged = false;
+    const record = withStoreLock(store, (records) => {
+      const target = findRecord(records, identifier);
+      if (!target) {
+        throw new Error(
+          `No execution found with UUID or session name: ${identifier}`
+        );
+      }
+      const owner = findRecord(records, name);
+      if (owner && owner.uuid !== target.uuid) {
+        throw new Error(
+          `Name "${name}" already refers to execution ${owner.uuid}`
+        );
+      }
+      const opts = (target.options = target.options || {});
+      const aliases = [...(opts.aliases || [])];
+      if (options.rename) {
+        const previous = opts.name || opts.sessionName || target.uuid;
+        if (previous === name) {
+          unchanged = true;
+          return null;
+        }
+        // A session name or UUID still resolves on its own; an earlier
+        // display name has to become an alias to keep resolving.
+        if (opts.name) {
+          aliases.push(previous);
+        }
+        opts.name = name;
+      } else if (owner) {
+        unchanged = true;
+        return null;
+      } else {
+        aliases.push(name);
+      }
+      opts.aliases = [...new Set(aliases)].filter((a) => a !== opts.name);
+      if (opts.aliases.length === 0) {
+        delete opts.aliases;
+      }
+      return target;
+    });
+    const current = record || store.get(identifier);
+    const action = options.rename ? 'Renamed' : 'Aliased';
+    return {
+      success: true,
+      output: `${unchanged ? 'Unchanged' : action} execution ${current.uuid}\naliases: [${executionAliases(current).join(', ')}]`,
+    };
+  } catch (error) {
+    return { success: false, error: error.message };
+  }
+}
+
+module.exports = {
+  executionAliases,
+  findRecord,
+  hasUserNames,
+  nameExecution,
+  withStoreLock,
+};

package/src/lib/execution-recovery.js

@@ -379,6 +379,23 @@ function recoverKilledExecution(params = {}) {
     }
   }
 
+  if (opts.commandHandoff && record.uuid) {
+    // `docker start` keeps the creation env; refresh START_ATTEMPT (#230).
+    try {
+      require('./docker-command-handoff').writeExecutionEnvHandoff(
+        containerName,
+        require('./execution-env').buildExecutionEnv({
+          executionId: record.uuid,
+          sessionName: containerName,
+          attempt: require('./execution-attempt').nextAttemptNumber(record),
+        }),
+        runner
+      );
+    } catch {
+      // Non-fatal: the command still runs, with the previous START_ATTEMPT.
+    }
+  }
+
   const since = now().toISOString();
   const {
     appendLifecycle,

package/src/lib/execution-resume.js

@@ -34,6 +34,7 @@ const {
   appendLifecycle,
   archiveAttempt,
   createAttempt,
+  nextAttemptNumber,
   patchAttempt,
 } = require('./execution-attempt');
 const { runCommand } = require('./execution-control');
@@ -46,6 +47,7 @@ const { SessionState, probeSession } = require('./session-probe');
 const { getDockerNetworks } = require('./docker-network-lifecycle');
 const {
   writeCommandHandoff,
+  writeExecutionEnvHandoff,
   buildCommandHandoffArgs,
   commandHandoffPath,
 } = require('./docker-command-handoff');
@@ -110,6 +112,8 @@ function buildLaunchOptions(record) {
     rootSession:
       opts.rootSession || opts.sessionNameHistory?.[0] || opts.sessionName,
     resumeCount: (Number(opts.resumeCount) || 0) + 1,
+    // START_ATTEMPT of the relaunched command (issue #230).
+    attemptNumber: nextAttemptNumber(record),
     image: opts.image || null,
     session: opts.sessionName,
     detached: true,
@@ -289,6 +293,7 @@ function buildResumePlan(
               session: newSessionName,
               containerName: newSessionName,
               sessionId: record.uuid,
+              attemptNumber: nextAttemptNumber(record),
               rootSession:
                 opts.rootSession || opts.sessionNameHistory?.[0] || sessionName,
               resumeCount: attempt,
@@ -657,6 +662,18 @@ async function resumeExecution(store, identifier, deps = {}) {
           );
         }
       }
+      if (plan.mode === ResumeMode.DOCKER_START && opts.commandHandoff) {
+        // `docker start` keeps the creation env; refresh START_ATTEMPT (#230).
+        writeExecutionEnvHandoff(
+          plan.sessionName,
+          require('./execution-env').buildExecutionEnv({
+            executionId: record.uuid,
+            sessionName: plan.sessionName,
+            attempt: attempt.number,
+          }),
+          runner
+        );
+      }
       for (const step of plan.steps) {
         let result;
         try {

package/src/lib/execution-store.js

@@ -77,6 +77,8 @@ class ExecutionRecord {
     this.endTime = options.endTime || null;
     this.attempt = options.attempt;
     this.attemptHistory = options.attemptHistory;
+    // UUID of the execution this one continues (`--continues`, issue #231).
+    this.continues = options.continues || undefined;
     // Provenance of `endTime` (issue #170.2). `--status` used to fabricate a
     // finish time with `new Date()` whenever the record had none, which made an
     // observation indistinguishable from a real finish time. One of
@@ -172,6 +174,9 @@ class ExecutionRecord {
     if (this.attemptHistory) {
       obj.attemptHistory = this.attemptHistory;
     }
+    if (this.continues) {
+      obj.continues = this.continues;
+    }
     if (this.endTimeSource !== undefined && this.endTimeSource !== null) {
       obj.endTimeSource = this.endTimeSource;
     }
@@ -544,33 +549,17 @@ class ExecutionStore {
   /**
    * Get an execution record by UUID or session name
    * First tries exact UUID match, then the current session name, then any
-   * session name the execution used before it was resumed
+   * session name the execution used before it was resumed, then the display
+   * name and aliases
    * @param {string} identifier - UUID or session name
    * @returns {ExecutionRecord|null}
    */
   get(identifier) {
-    const records = this.readLinoRecords();
-    // First try exact UUID match
-    const byUuid = records.find((r) => r.uuid === identifier);
-    if (byUuid) {
-      return byUuid;
-    }
-    // Fall back to session name lookup (stored in options.sessionName)
-    const bySessionName = records.find(
-      (r) => r.options && r.options.sessionName === identifier
-    );
-    if (bySessionName) {
-      return bySessionName;
-    }
-    // Finally, honor session names this record used before it was resumed, so
-    // one logical session stays addressable across restarts (issue #162).
-    const byPreviousSessionName = records.find(
-      (r) =>
-        r.options &&
-        Array.isArray(r.options.sessionNameHistory) &&
-        r.options.sessionNameHistory.includes(identifier)
+    // Names, display names and aliases resolve too (issues #162, #231).
+    return require('./execution-identity').findRecord(
+      this.readLinoRecords(),
+      identifier
     );
-    return byPreviousSessionName || null;
   }
 
   /**

package/src/lib/isolation.js

@@ -201,7 +201,8 @@ function runScreenWithLogCapture(
   sessionName,
   shellInfo,
   user = null,
-  logPath = null
+  logPath = null,
+  env = null
 ) {
   return _runScreenWithLogCapture(
     command,
@@ -210,7 +211,8 @@ function runScreenWithLogCapture(
     user,
     wrapCommandWithUser,
     isInteractiveShellCommand,
-    logPath
+    logPath,
+    env
   );
 }
 
@@ -241,6 +243,7 @@ function runInScreen(command, options = {}) {
           keepAlive: options.keepAlive,
           logPath: options.logPath,
           wrapCommandWithUser,
+          env: options.executionEnv,
         })
       );
     } else {
@@ -249,7 +252,8 @@ function runInScreen(command, options = {}) {
         sessionName,
         shellInfo,
         options.user,
-        options.logPath
+        options.logPath,
+        options.executionEnv
       );
     }
   } catch (err) {
@@ -909,6 +913,20 @@ function runIsolated(backend, command, options = {}) {
     session: options.sessionStack ? options.sessionStack[0] : options.session,
     logPath: options.logPath,
   };
+  // START_* identity (issue #230): docker passes it with `-e`; a bare screen
+  // shell inherits the spawn env; everything else gets an `export` prefix.
+  const identity = require('./execution-env');
+  currentOptions.executionEnv =
+    identity.executionEnvFromOptions(currentOptions);
+  if (
+    backend !== 'docker' &&
+    !(backend === 'screen' && isInteractiveShellCommand(effectiveCommand))
+  ) {
+    effectiveCommand = identity.prefixWithExecutionEnv(
+      effectiveCommand,
+      currentOptions.executionEnv
+    );
+  }
 
   switch (backend) {
     case 'screen':

package/src/lib/launch-identity-options.js

@@ -0,0 +1,81 @@
+/**
+ * Launch options about the identity of a new execution:
+ *   --append-attempt    run as the next attempt of the tracked execution named
+ *                       by --session-id instead of being refused (issue #229)
+ *   --continues <id>    record that this execution continues an earlier one,
+ *                       which `--status` and `--upload-log` follow (issue #231)
+ *
+ * Both only apply when a command is launched, not to the query modes.
+ */
+const { activeQueryModes } = require('./args-parser-queries');
+
+function createLaunchIdentityOptionDefaults() {
+  return {
+    appendAttempt: false,
+    continues: null,
+  };
+}
+
+/**
+ * Parse one launch identity option.
+ * @param {string[]} args - Arguments array
+ * @param {number} index - Current index
+ * @param {object} options - Options object to populate
+ * @returns {number} Number of arguments consumed (0 if not recognized)
+ */
+function parse(args, index, options) {
+  const arg = args[index];
+  if (arg === '--append-attempt') {
+    options.appendAttempt = true;
+    return 1;
+  }
+  if (arg === '--continues') {
+    if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
+      options.continues = args[index + 1];
+      return 2;
+    }
+    throw new Error(
+      'Option --continues requires a UUID or session name argument'
+    );
+  }
+  if (arg.startsWith('--continues=')) {
+    const value = arg.slice('--continues='.length);
+    if (!value) {
+      throw new Error(
+        'Option --continues requires a UUID or session name argument'
+      );
+    }
+    options.continues = value;
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * Validate the launch identity options.
+ * @param {object} options - Parsed wrapper options
+ * @throws {Error} When the combination is not supported
+ */
+function validate(options) {
+  const used = [
+    ...(options.appendAttempt ? ['--append-attempt'] : []),
+    ...(options.continues !== null && options.continues !== undefined
+      ? ['--continues']
+      : []),
+  ];
+  if (used.length === 0) {
+    return;
+  }
+  if (activeQueryModes(options).length > 0) {
+    throw new Error(`${used[0]} option is only valid when launching a command`);
+  }
+  if (options.appendAttempt && !options.sessionId) {
+    throw new Error('--append-attempt option requires --session-id <uuid>');
+  }
+}
+
+module.exports = {
+  createLaunchIdentityOptionDefaults,
+  parse,
+  validate,
+};