start-command 0.25.0 → 0.25.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # start-command
 
+## 0.25.2
+
+### Patch Changes
+
+- 8f58d2b: fix: support --session name lookups in --status and track detached session lifecycle
+
+  `--status` now accepts session names in addition to UUIDs. Detached mode no longer incorrectly reports immediate completion — status is determined at query time by checking if the actual session is still running.
+
+## 0.25.1
+
+### Patch Changes
+
+- da6df0e: fix: correct license field from MIT to Unlicense (public domain)
+
+  Updated `package.json` to correctly reflect the Unlicense (public domain) license instead of MIT. The project's `LICENSE` file has always contained the Unlicense text; this change aligns the metadata with the actual license.
+
+  Fixes #99
+
 ## 0.25.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {
@@ -32,7 +32,7 @@
     "automation"
   ],
   "author": "",
-  "license": "MIT",
+  "license": "Unlicense",
   "engines": {
     "bun": ">=1.0.0"
   },

package/src/bin/cli.js

@@ -333,7 +333,7 @@ Options:
   --auto-remove-docker-container  Auto-remove docker container after exit
   --shell <shell>       Shell to use in isolation environments: auto, bash, zsh, sh (default: auto)
   --use-command-stream  Use command-stream library for execution (experimental)
-  --status <uuid>       Show status of execution by UUID (--output-format: links-notation|json|text)
+  --status <id>         Show status of execution by UUID or session name (--output-format: links-notation|json|text)
   --cleanup             Clean up stale "executing" records (crashed/killed processes)
   --cleanup-dry-run     Show stale records that would be cleaned up (without cleaning)
   --version, -v         Show version information
@@ -468,12 +468,9 @@ async function runWithIsolation(
     }
   }
 
-  // Add isolation info to extra lines
+  // Add isolation info to extra lines (session name for reconnecting, see issue #67)
   if (environment) {
     extraLines.push(`[Isolation] Environment: ${environment}, Mode: ${mode}`);
-    // Always add the session name so users can reconnect to detached sessions
-    // This is important for screen, tmux, docker where the session/container name
-    // is different from the session UUID used for tracking (see issue #67)
     extraLines.push(`[Isolation] Session: ${sessionName}`);
   }
   if (effectiveImage) {
@@ -602,9 +599,11 @@ async function runWithIsolation(
   // Write log file
   writeLogFile(logFilePath, logContent);
 
-  // Update execution record as completed and clear global reference
+  // Update execution record: detached keeps "executing" (resolved at query time)
   if (executionRecord && store) {
-    executionRecord.complete(exitCode);
+    if (mode !== 'detached') {
+      executionRecord.complete(exitCode);
+    }
     try {
       store.save(executionRecord);
     } catch (err) {
@@ -614,7 +613,6 @@ async function runWithIsolation(
         );
       }
     }
-    // Clear global reference since we've completed normally
     currentExecutionRecord = null;
   }
 

package/src/lib/args-parser.js

@@ -418,13 +418,13 @@ function parseOption(args, index, options) {
     return 1;
   }
 
-  // --status <uuid>
+  // --status <uuid-or-session-name>
   if (arg === '--status') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
       options.status = args[index + 1];
       return 2;
     } else {
-      throw new Error(`Option ${arg} requires a UUID argument`);
+      throw new Error(`Option ${arg} requires a UUID or session name argument`);
     }
   }
 

package/src/lib/execution-store.js

@@ -470,14 +470,23 @@ class ExecutionStore {
   }
 
   /**
-   * Get an execution record by UUID
-   * @param {string} uuid
+   * Get an execution record by UUID or session name
+   * First tries exact UUID match, then falls back to session name lookup
+   * @param {string} identifier - UUID or session name
    * @returns {ExecutionRecord|null}
    */
-  get(uuid) {
+  get(identifier) {
     const records = this.readLinoRecords();
-    const found = records.find((r) => r.uuid === uuid);
-    return found || null;
+    // 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
+    );
+    return bySessionName || null;
   }
 
   /**

package/src/lib/status-formatter.js

@@ -7,11 +7,108 @@
  * - Text: Human-readable text format
  */
 
+const { execSync } = require('child_process');
 const {
   escapeForLinksNotation,
   formatAsNestedLinksNotation,
 } = require('./output-blocks');
 
+/**
+ * Check if a detached isolation session is still running
+ * @param {Object} record - Execution record
+ * @returns {boolean|null} true if running, false if not, null if unable to determine
+ */
+function isDetachedSessionAlive(record) {
+  const opts = record.options || {};
+  const sessionName = opts.sessionName;
+  const isolationMode = opts.isolationMode;
+  const isolated = opts.isolated;
+
+  if (!sessionName || isolationMode !== 'detached') {
+    return null;
+  }
+
+  try {
+    switch (isolated) {
+      case 'screen': {
+        const output = execSync('screen -ls', {
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return output.includes(sessionName);
+      }
+      case 'tmux': {
+        execSync(`tmux has-session -t ${sessionName}`, {
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+      }
+      case 'docker': {
+        const output = execSync(
+          `docker inspect -f "{{.State.Running}}" ${sessionName}`,
+          { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+        );
+        return output.trim() === 'true';
+      }
+      case 'ssh': {
+        // For SSH, check if the PID is still running on remote would require
+        // re-connecting. Fall back to checking the local wrapper PID.
+        if (record.pid) {
+          try {
+            process.kill(record.pid, 0);
+            return true;
+          } catch {
+            return false;
+          }
+        }
+        return null;
+      }
+      default:
+        return null;
+    }
+  } catch {
+    // Command failed - session is likely not running
+    return false;
+  }
+}
+
+/**
+ * Enrich execution record with live session status for detached executions.
+ * If a record shows "executing" but the detached session has actually ended,
+ * returns an updated copy with status "executed". If it shows "executed" but
+ * the session is still running, returns a copy with status "executing".
+ * @param {Object} record - Execution record
+ * @returns {Object} Possibly updated execution record
+ */
+function enrichDetachedStatus(record) {
+  const alive = isDetachedSessionAlive(record);
+  if (alive === null) {
+    return record;
+  }
+
+  // Create a shallow copy to avoid mutating the original
+  const enriched = Object.create(Object.getPrototypeOf(record));
+  Object.assign(enriched, record);
+
+  if (alive && enriched.status === 'executed') {
+    // Session still running but record says executed - correct it
+    enriched.status = 'executing';
+    enriched.exitCode = null;
+    enriched.endTime = null;
+  } else if (!alive && enriched.status === 'executing') {
+    // Session ended but record says executing - correct it
+    enriched.status = 'executed';
+    if (enriched.exitCode === null || enriched.exitCode === undefined) {
+      enriched.exitCode = -1; // Unknown exit code
+    }
+    if (!enriched.endTime) {
+      enriched.endTime = new Date().toISOString();
+    }
+  }
+
+  return enriched;
+}
+
 /**
  * Format execution record as Links Notation (indented style)
  * Uses nested Links notation for object values (like options) instead of JSON
@@ -122,18 +219,23 @@ function formatRecord(record, format) {
  * @param {string|null} outputFormat - Output format (links-notation, json, text)
  * @returns {{success: boolean, output?: string, error?: string}}
  */
-function queryStatus(store, uuid, outputFormat) {
+function queryStatus(store, identifier, outputFormat) {
   if (!store) {
     return { success: false, error: 'Execution tracking is disabled.' };
   }
-  const record = store.get(uuid);
+  const record = store.get(identifier);
   if (!record) {
-    return { success: false, error: `No execution found with UUID: ${uuid}` };
+    return {
+      success: false,
+      error: `No execution found with UUID or session name: ${identifier}`,
+    };
   }
   try {
+    // Enrich detached execution status with live session check
+    const enrichedRecord = enrichDetachedStatus(record);
     return {
       success: true,
-      output: formatRecord(record, outputFormat || 'links-notation'),
+      output: formatRecord(enrichedRecord, outputFormat || 'links-notation'),
     };
   } catch (err) {
     return { success: false, error: err.message };
@@ -145,4 +247,6 @@ module.exports = {
   formatRecordAsText,
   formatRecord,
   queryStatus,
+  isDetachedSessionAlive,
+  enrichDetachedStatus,
 };

package/test/session-name-status.test.js

@@ -0,0 +1,311 @@
+/**
+ * Tests for --status lookup by session name and detached status enrichment
+ * Issue #101: --session name not usable with --status, and --detached reports immediate completion
+ */
+
+const { describe, it, expect, beforeEach, afterEach } = require('bun:test');
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const {
+  ExecutionStore,
+  ExecutionRecord,
+  ExecutionStatus,
+} = require('../src/lib/execution-store');
+const {
+  queryStatus,
+  isDetachedSessionAlive,
+  enrichDetachedStatus,
+} = require('../src/lib/status-formatter');
+
+// Use temp directory for tests
+const TEST_APP_FOLDER = path.join(
+  os.tmpdir(),
+  `session-name-status-test-${Date.now()}`
+);
+
+// Path to CLI
+const CLI_PATH = path.join(__dirname, '../src/bin/cli.js');
+
+// Helper to clean up test directory
+function cleanupTestDir() {
+  if (fs.existsSync(TEST_APP_FOLDER)) {
+    fs.rmSync(TEST_APP_FOLDER, { recursive: true, force: true });
+  }
+}
+
+// Helper to run CLI command
+function runCli(args, env = {}) {
+  const result = spawnSync('bun', [CLI_PATH, ...args], {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      START_APP_FOLDER: TEST_APP_FOLDER,
+      ...env,
+    },
+    timeout: 10000,
+  });
+  return {
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    exitCode: result.status,
+  };
+}
+
+describe('Issue #101: --status with session name lookup', () => {
+  let store;
+
+  beforeEach(() => {
+    cleanupTestDir();
+    store = new ExecutionStore({
+      appFolder: TEST_APP_FOLDER,
+      useLinks: false,
+    });
+  });
+
+  afterEach(() => {
+    cleanupTestDir();
+  });
+
+  describe('ExecutionStore.get() session name lookup', () => {
+    it('should find record by UUID', () => {
+      const record = new ExecutionRecord({
+        command: 'echo hello',
+        pid: 12345,
+        logPath: '/tmp/test.log',
+        options: { sessionName: 'my-custom-session' },
+      });
+      record.complete(0);
+      store.save(record);
+
+      const found = store.get(record.uuid);
+      expect(found).not.toBeNull();
+      expect(found.uuid).toBe(record.uuid);
+    });
+
+    it('should find record by session name', () => {
+      const record = new ExecutionRecord({
+        command: 'sleep 60',
+        pid: 12345,
+        logPath: '/tmp/test.log',
+        options: {
+          sessionName: 'my-custom-session',
+          isolated: 'screen',
+          isolationMode: 'detached',
+        },
+      });
+      store.save(record);
+
+      const found = store.get('my-custom-session');
+      expect(found).not.toBeNull();
+      expect(found.uuid).toBe(record.uuid);
+      expect(found.options.sessionName).toBe('my-custom-session');
+    });
+
+    it('should prefer UUID match over session name', () => {
+      // Create two records: one whose session name matches the UUID of another
+      const record1 = new ExecutionRecord({
+        command: 'echo first',
+        pid: 111,
+        logPath: '/tmp/first.log',
+        options: { sessionName: 'some-session' },
+      });
+      record1.complete(0);
+      store.save(record1);
+
+      const record2 = new ExecutionRecord({
+        command: 'echo second',
+        pid: 222,
+        logPath: '/tmp/second.log',
+        options: { sessionName: record1.uuid }, // session name matches record1's UUID
+      });
+      store.save(record2);
+
+      // Looking up by record1's UUID should return record1, not record2
+      const found = store.get(record1.uuid);
+      expect(found.command).toBe('echo first');
+    });
+
+    it('should return null for non-existent session name', () => {
+      const found = store.get('nonexistent-session');
+      expect(found).toBeNull();
+    });
+
+    it('should return null for record without session name', () => {
+      const record = new ExecutionRecord({
+        command: 'echo hello',
+        pid: 12345,
+        logPath: '/tmp/test.log',
+      });
+      store.save(record);
+
+      const found = store.get('some-session-name');
+      expect(found).toBeNull();
+    });
+  });
+
+  describe('queryStatus() with session name', () => {
+    it('should query status by session name', () => {
+      const record = new ExecutionRecord({
+        command: 'sleep 60',
+        pid: 12345,
+        logPath: '/tmp/test.log',
+        options: {
+          sessionName: 'my-test-session',
+          isolated: 'screen',
+          isolationMode: 'attached',
+        },
+      });
+      record.complete(0);
+      store.save(record);
+
+      const result = queryStatus(store, 'my-test-session', 'json');
+      expect(result.success).toBe(true);
+
+      const parsed = JSON.parse(result.output);
+      expect(parsed.uuid).toBe(record.uuid);
+      expect(parsed.command).toBe('sleep 60');
+    });
+
+    it('should show error for non-existent session name', () => {
+      const result = queryStatus(store, 'nonexistent-session', 'json');
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('No execution found');
+      expect(result.error).toContain('nonexistent-session');
+    });
+  });
+
+  describe('CLI --status with session name', () => {
+    it('should query by session name via CLI', () => {
+      const record = new ExecutionRecord({
+        command: 'echo hello world',
+        pid: 12345,
+        logPath: '/tmp/test.log',
+        options: {
+          sessionName: 'cli-test-session',
+          isolated: 'screen',
+          isolationMode: 'attached',
+        },
+      });
+      record.complete(0);
+      store.save(record);
+
+      const result = runCli([
+        '--status',
+        'cli-test-session',
+        '--output-format',
+        'json',
+      ]);
+
+      expect(result.exitCode).toBe(0);
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.uuid).toBe(record.uuid);
+      expect(parsed.command).toBe('echo hello world');
+      expect(parsed.status).toBe('executed');
+    });
+
+    it('should show error for non-existent session name via CLI', () => {
+      const result = runCli(['--status', 'nonexistent-session']);
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toContain('No execution found');
+    });
+  });
+});
+
+describe('Issue #101: Detached status enrichment', () => {
+  describe('isDetachedSessionAlive()', () => {
+    it('should return null for non-detached records', () => {
+      const record = new ExecutionRecord({
+        command: 'echo hello',
+        options: {
+          sessionName: 'test',
+          isolated: 'screen',
+          isolationMode: 'attached',
+        },
+      });
+      expect(isDetachedSessionAlive(record)).toBeNull();
+    });
+
+    it('should return null for records without session name', () => {
+      const record = new ExecutionRecord({
+        command: 'echo hello',
+        options: { isolationMode: 'detached' },
+      });
+      expect(isDetachedSessionAlive(record)).toBeNull();
+    });
+
+    it('should return false for non-existent screen session', () => {
+      const record = new ExecutionRecord({
+        command: 'sleep 60',
+        options: {
+          sessionName: 'nonexistent-screen-session-test-101',
+          isolated: 'screen',
+          isolationMode: 'detached',
+        },
+      });
+      const alive = isDetachedSessionAlive(record);
+      // May be false or null depending on whether screen is installed
+      if (alive !== null) {
+        expect(alive).toBe(false);
+      }
+    });
+
+    it('should return false for non-existent docker container', () => {
+      const record = new ExecutionRecord({
+        command: 'sleep 60',
+        options: {
+          sessionName: 'nonexistent-docker-container-test-101',
+          isolated: 'docker',
+          isolationMode: 'detached',
+        },
+      });
+      const alive = isDetachedSessionAlive(record);
+      // May be false or null depending on whether docker is installed
+      if (alive !== null) {
+        expect(alive).toBe(false);
+      }
+    });
+  });
+
+  describe('enrichDetachedStatus()', () => {
+    it('should not modify non-detached records', () => {
+      const record = new ExecutionRecord({
+        command: 'echo hello',
+        options: {
+          sessionName: 'test',
+          isolated: 'screen',
+          isolationMode: 'attached',
+        },
+      });
+      record.complete(0);
+
+      const enriched = enrichDetachedStatus(record);
+      expect(enriched.status).toBe('executed');
+      expect(enriched.exitCode).toBe(0);
+    });
+
+    it('should mark non-running detached session as executed', () => {
+      const record = new ExecutionRecord({
+        command: 'sleep 60',
+        options: {
+          sessionName: 'nonexistent-session-enrich-test-101',
+          isolated: 'screen',
+          isolationMode: 'detached',
+        },
+      });
+      // Record says executing, but session doesn't exist
+
+      const enriched = enrichDetachedStatus(record);
+      // If screen is available, should mark as executed
+      // If screen is not available, should return unchanged
+      if (enriched.status === 'executed') {
+        expect(enriched.exitCode).toBe(-1); // Unknown exit code
+        expect(enriched.endTime).not.toBeNull();
+      }
+    });
+  });
+});
+
+console.log('=== Session Name Status Tests (Issue #101) ===');