start-command 0.13.0 → 0.16.0

package/docs/case-studies/issue-28/issue-data.json

@@ -1,105 +0,0 @@
-{
-  "issue": {
-    "number": 28,
-    "title": "Can we somehow overcome the need of `'` quotes with `|` and `\"` in a sequence?",
-    "url": "https://github.com/link-foundation/start/issues/28",
-    "state": "open",
-    "labels": ["bug", "documentation", "enhancement", "question"],
-    "author": "konard",
-    "created_at": "2025-12-24"
-  },
-  "environment": {
-    "platform": "darwin",
-    "shell": "/bin/zsh",
-    "bun_version": "1.2.20",
-    "working_directory": "/Users/konard"
-  },
-  "scenarios": [
-    {
-      "name": "unquoted_command",
-      "input": "$ echo \"hi\" | agent",
-      "timestamp": "2025-12-24 15:07:08.894",
-      "shell_interpretation": {
-        "command_1": "$ echo \"hi\"",
-        "operator": "|",
-        "command_2": "agent"
-      },
-      "actual_execution": {
-        "start_command_received": "echo \"hi\"",
-        "start_command_output": "hi",
-        "agent_received": "JSON output from start-command stdout"
-      },
-      "user_expectation": "agent should receive 'hi' from echo",
-      "actual_result": "agent received start-command JSON output",
-      "exit_code": 0
-    },
-    {
-      "name": "quoted_command",
-      "input": "$ 'echo \"hi\" | agent'",
-      "timestamp": "2025-12-24 15:07:33.420",
-      "shell_interpretation": {
-        "command": "$",
-        "argument": "echo \"hi\" | agent"
-      },
-      "actual_execution": {
-        "start_command_received": "echo \"hi\" | agent",
-        "pipeline_executed": true,
-        "echo_output": "hi",
-        "agent_received": "hi"
-      },
-      "user_expectation": "agent should receive 'hi' from echo",
-      "actual_result": "agent received 'hi' from echo",
-      "exit_code": 0
-    }
-  ],
-  "root_cause": {
-    "category": "shell_parsing_behavior",
-    "is_bug": false,
-    "description": "The pipe operator (|) is a shell metacharacter that is parsed by the shell before command arguments are passed. This is standard POSIX shell behavior, not a bug in start-command.",
-    "affected_shells": ["bash", "zsh", "sh", "dash", "ksh"],
-    "shell_parsing_order": [
-      "1. Tokenization - command line split into tokens",
-      "2. Operator recognition - | && || ; & recognized as metacharacters",
-      "3. Command grouping - commands grouped based on operators",
-      "4. Quote processing - quoted strings preserved",
-      "5. Expansion - variables, commands, etc. expanded"
-    ]
-  },
-  "solutions": {
-    "recommended": "documentation_enhancement",
-    "options": [
-      {
-        "id": "documentation_enhancement",
-        "name": "Documentation Enhancement",
-        "description": "Add clear documentation about quoting requirements",
-        "pros": ["No code changes", "Educates users", "POSIX compliant"],
-        "cons": ["Requires users to learn quoting rules"],
-        "complexity": "low"
-      },
-      {
-        "id": "warning_detection",
-        "name": "Optional Warning Detection",
-        "description": "Detect when stdout is piped and emit helpful warning",
-        "pros": ["Helps users understand behavior", "Non-breaking"],
-        "cons": ["May add noise to output"],
-        "complexity": "medium"
-      },
-      {
-        "id": "here_document",
-        "name": "Here-Document Wrapper",
-        "description": "Support $$ <<'CMD' syntax for multi-line commands",
-        "pros": ["No quoting issues", "Clear syntax"],
-        "cons": ["More verbose", "New syntax to learn"],
-        "complexity": "high"
-      }
-    ]
-  },
-  "references": {
-    "bash_manual": "https://www.gnu.org/software/bash/manual/bash.html",
-    "pipelines_doc": "https://www.gnu.org/software/bash/manual/html_node/Pipelines.html",
-    "quoting_doc": "https://www.gnu.org/software/bash/manual/html_node/Quoting.html",
-    "posix_shell": "https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html"
-  },
-  "analysis_date": "2025-12-24",
-  "analyst": "AI Issue Solver"
-}

package/docs/case-studies/issue-28/raw-issue-data.md

@@ -1,92 +0,0 @@
-# Issue #28 Raw Data
-
-## Issue Title
-
-Can we somehow overcome the need of `'` quotes with `|` and `"` in a sequence?
-
-## Issue State
-
-OPEN
-
-## Issue Labels
-
-bug, documentation, enhancement, question
-
-## Issue Author
-
-konard
-
-## Issue Content
-
-The issue shows two terminal sessions demonstrating different behaviors:
-
-### Session 1: Without quoting the entire command
-
-```bash
-konard@MacBook-Pro-Konstantin ~ % $ echo "hi" | agent
-```
-
-**Result:** The `echo "hi"` command ran directly in the shell, and only its OUTPUT was piped to `agent`. The agent then processed the log file that was created by the `$` command (start-command), not the original command input.
-
-The agent received the OUTPUT of `$ echo "hi"` which was captured in a log file, and then read that log file.
-
-### Session 2: With quoting the entire command
-
-```bash
-konard@MacBook-Pro-Konstantin ~ % $ 'echo "hi" | agent'
-```
-
-**Result:** The entire string `echo "hi" | agent` was passed TO the `$` command (start-command). The start-command then executed this complete pipeline, which resulted in the `echo "hi"` output being piped to `agent` correctly.
-
-## Terminal Logs
-
-### Session 1 Output (problematic behavior)
-
-```json
-{
-  "type": "status",
-  "mode": "stdin-stream",
-  "message": "Agent CLI in continuous listening mode. Accepts JSON and plain text input.",
-  "hint": "Press CTRL+C to exit. Use --help for options.",
-  "acceptedFormats": ["JSON object with \"message\" field", "Plain text"],
-  "options": {
-    "interactive": true,
-    "autoMergeQueuedMessages": true,
-    "alwaysAcceptStdin": true,
-    "compactJson": false
-  }
-}
-```
-
-The agent then read a log file:
-
-```
-=== Start Command Log ===
-Timestamp: 2025-12-24 15:07:08.894
-Command: echo hi
-Shell: /bin/zsh
-Platform: darwin
-Bun Version: 1.2.20
-Working Directory: /Users/konard
-==================================================
-
-hi
-
-==================================================
-Finished: 2025-12-24 15:07:08.906
-Exit Code: 0
-```
-
-And responded:
-
-> "It looks like you executed the command `echo hi`, which successfully output \"hi\" with exit code 0..."
-
-### Session 2 Output (desired behavior)
-
-The agent received "hi" directly as input and responded:
-
-> "Hello! How can I help you today?"
-
-## User Request
-
-> Please download all logs and data related about the issue to this repository, make sure we compile that data to `./docs/case-studies/issue-{id}` folder, and use it to do deep case study analysis (also make sure to search online for additional facts and data), in which we will reconstruct timeline/sequence of events, find root causes of the problem, and propose possible solutions.

package/experiments/debug-regex.js

@@ -1,49 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Debug script to understand regex generation
- */
-
-const { createRule, parseLinoContent } = require('../src/lib/substitution');
-
-// Test creating a simple rule
-const rule = createRule(
-  'install $packageName npm package',
-  'npm install $packageName'
-);
-
-console.log('Pattern:', 'install $packageName npm package');
-console.log('Replacement:', 'npm install $packageName');
-console.log('Generated Regex:', rule.regex);
-console.log('Variables:', rule.variables);
-console.log('');
-
-// Test matching
-const input = 'install gh-upload-log npm package';
-const match = input.match(rule.regex);
-console.log('Input:', input);
-console.log('Match result:', match);
-
-if (match) {
-  console.log('Groups:', match.groups);
-}
-
-// Test simpler lino content
-const simpleContent = `
-(install $packageName npm package)
-(npm install $packageName)
-`;
-
-const rules = parseLinoContent(simpleContent);
-console.log(
-  '\nParsed rules:',
-  JSON.stringify(
-    rules,
-    (key, value) => {
-      if (key === 'regex') {
-        return value.toString();
-      }
-      return value;
-    },
-    2
-  )
-);

package/experiments/isolation-design.md

@@ -1,131 +0,0 @@
-# Isolation Support Design
-
-## Overview
-
-This document outlines the design for adding process isolation support to start-command.
-
-## Supported Isolation Backends
-
-### Terminal Multiplexers
-
-1. **screen** - GNU Screen, classic session manager
-2. **tmux** - Modern terminal multiplexer
-
-### Container Isolation
-
-3. **docker** - Docker containers
-
-## Command Syntax
-
-Two syntax patterns are supported:
-
-```bash
-# Pattern 1: Using -- separator
-$ [wrapper-options] -- [command] [command-options]
-
-# Pattern 2: Options before command
-$ [wrapper-options] command [command-options]
-```
-
-### Wrapper Options
-
-- `--isolated <backend>` or `-i <backend>`: Run command in isolated environment
-  - Backends: `screen`, `tmux`, `docker`
-- `--attached` or `-a`: Run in attached mode (foreground)
-- `--detached` or `-d`: Run in detached mode (background)
-- `--session <name>` or `-s <name>`: Name for the session (optional)
-
-### Examples
-
-```bash
-# Run in tmux (attached by default for multiplexers)
-$ --isolated tmux -- npm test
-
-# Run in screen detached
-$ --isolated screen --detached -- npm start
-
-# Run in docker container
-$ --isolated docker --image node:20 -- npm install
-
-# Short form
-$ -i tmux -d npm start
-```
-
-## Mode Behavior
-
-### Attached Mode (--attached)
-
-- Default for terminal multiplexers (screen, tmux)
-- Command runs in foreground
-- User can interact with the terminal
-- For docker: runs with -it flags
-
-### Detached Mode (--detached)
-
-- Command runs in background
-- For multiplexers: creates a session that can be reattached later
-- For docker: runs with -d flag
-- Session info is printed for later access
-
-### Error Handling
-
-- If both --attached and --detached are specified, throw an error
-- Error message should ask user to choose only one
-
-## Implementation Details
-
-### Session Naming
-
-- Auto-generate session name: `start-{timestamp}-{random}`
-- Allow custom name via --session option
-- Session names used for reattachment
-
-### Backend Commands
-
-#### Screen
-
-```bash
-# Attached
-screen -S <session> bash -c '<command>'
-
-# Detached
-screen -dmS <session> bash -c '<command>'
-```
-
-#### Tmux
-
-```bash
-# Attached
-tmux new-session -s <session> '<command>'
-
-# Detached
-tmux new-session -d -s <session> '<command>'
-```
-
-#### Docker
-
-```bash
-# Attached
-docker run -it --name <name> <image> <command>
-
-# Detached
-docker run -d --name <name> <image> <command>
-```
-
-## Testing Strategy
-
-### Unit Tests
-
-- Argument parsing tests
-- Backend detection tests
-- Session name generation tests
-- Conflict detection (attached + detached)
-
-### Integration Tests
-
-- Actual execution with mocked backends
-- End-to-end tests with real backends (when available)
-
-### E2E Tests
-
-- Full workflow tests with screen/tmux (if installed)

package/experiments/screen-output-test.js

@@ -1,265 +0,0 @@
-#!/usr/bin/env node
-/**
- * Experiment: Test screen output capture behavior
- *
- * This experiment tests different approaches to capture output from GNU screen
- * sessions, specifically addressing issue #25 where output is lost on macOS
- * with screen 4.00.03.
- */
-
-const { execSync, spawn, spawnSync } = require('child_process');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-// Check if screen is available
-function isScreenAvailable() {
-  try {
-    execSync('which screen', { stdio: ['pipe', 'pipe', 'pipe'] });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// Get screen version
-function getScreenVersion() {
-  try {
-    const output = execSync('screen --version', {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-    const match = output.match(/(\d+)\.(\d+)\.(\d+)/);
-    if (match) {
-      return {
-        major: parseInt(match[1], 10),
-        minor: parseInt(match[2], 10),
-        patch: parseInt(match[3], 10),
-        raw: output.trim(),
-      };
-    }
-  } catch {
-    // Ignore
-  }
-  return null;
-}
-
-// Check if -Logfile is supported (screen >= 4.5.1)
-function supportsLogfileOption(version) {
-  if (!version) {
-    return false;
-  }
-  if (version.major > 4) {
-    return true;
-  }
-  if (version.major < 4) {
-    return false;
-  }
-  if (version.minor > 5) {
-    return true;
-  }
-  if (version.minor < 5) {
-    return false;
-  }
-  return version.patch >= 1;
-}
-
-// Test 1: Direct screen invocation (current approach for TTY)
-async function testDirectScreen(command) {
-  console.log('\n=== Test 1: Direct screen invocation (TTY mode) ===');
-  const sessionName = `test-direct-${Date.now()}`;
-  const shell = process.env.SHELL || '/bin/sh';
-
-  console.log(`Command: screen -S ${sessionName} ${shell} -c '${command}'`);
-  console.log('Note: This approach loses output for quick commands');
-
-  // This is what happens currently with TTY
-  return new Promise((resolve) => {
-    const child = spawn('screen', ['-S', sessionName, shell, '-c', command], {
-      stdio: 'inherit',
-    });
-
-    child.on('exit', (code) => {
-      console.log(`Exit code: ${code}`);
-      resolve({ success: code === 0, output: '(output not captured)' });
-    });
-
-    child.on('error', (err) => {
-      console.error(`Error: ${err.message}`);
-      resolve({ success: false, output: '' });
-    });
-  });
-}
-
-// Test 2: Detached screen with log file (current approach for no-TTY)
-async function testDetachedWithLog(command) {
-  console.log('\n=== Test 2: Detached screen with log capture ===');
-  const sessionName = `test-detached-${Date.now()}`;
-  const shell = process.env.SHELL || '/bin/sh';
-  const logFile = path.join(os.tmpdir(), `screen-test-${sessionName}.log`);
-
-  const version = getScreenVersion();
-  const useNativeLogging = supportsLogfileOption(version);
-
-  console.log(`Screen version: ${version ? version.raw : 'unknown'}`);
-  console.log(`Supports -Logfile: ${useNativeLogging}`);
-
-  let screenArgs;
-  let effectiveCommand = command;
-
-  if (useNativeLogging) {
-    // Modern screen
-    screenArgs = [
-      '-dmS',
-      sessionName,
-      '-L',
-      '-Logfile',
-      logFile,
-      shell,
-      '-c',
-      command,
-    ];
-  } else {
-    // Older screen - use tee fallback
-    effectiveCommand = `(${command}) 2>&1 | tee "${logFile}"`;
-    screenArgs = ['-dmS', sessionName, shell, '-c', effectiveCommand];
-  }
-
-  console.log(`Command: screen ${screenArgs.join(' ')}`);
-
-  return new Promise((resolve) => {
-    try {
-      const result = spawnSync('screen', screenArgs, { stdio: 'inherit' });
-
-      if (result.error) {
-        console.error(`Error: ${result.error.message}`);
-        resolve({ success: false, output: '' });
-        return;
-      }
-
-      // Poll for session completion
-      const checkInterval = 100;
-      const maxWait = 10000;
-      let waited = 0;
-
-      const checkCompletion = () => {
-        try {
-          const sessions = execSync('screen -ls', {
-            encoding: 'utf8',
-            stdio: ['pipe', 'pipe', 'pipe'],
-          });
-
-          if (!sessions.includes(sessionName)) {
-            // Session ended
-            let output = '';
-            try {
-              output = fs.readFileSync(logFile, 'utf8');
-              console.log(`Captured output: "${output.trim()}"`);
-              fs.unlinkSync(logFile);
-            } catch {
-              console.log('Log file not found or empty');
-            }
-            resolve({ success: true, output });
-            return;
-          }
-
-          waited += checkInterval;
-          if (waited >= maxWait) {
-            resolve({ success: false, output: 'timeout' });
-            return;
-          }
-
-          setTimeout(checkCompletion, checkInterval);
-        } catch {
-          let output = '';
-          try {
-            output = fs.readFileSync(logFile, 'utf8');
-            console.log(`Captured output: "${output.trim()}"`);
-            fs.unlinkSync(logFile);
-          } catch {
-            // Ignore
-          }
-          resolve({ success: true, output });
-        }
-      };
-
-      setTimeout(checkCompletion, checkInterval);
-    } catch (err) {
-      console.error(`Error: ${err.message}`);
-      resolve({ success: false, output: '' });
-    }
-  });
-}
-
-// Test 3: Script command for output capture (alternative approach)
-async function testScriptCapture(command) {
-  console.log('\n=== Test 3: Using script command for output capture ===');
-  const logFile = path.join(os.tmpdir(), `script-test-${Date.now()}.log`);
-  const shell = process.env.SHELL || '/bin/sh';
-
-  // Use 'script' command which is available on both macOS and Linux
-  // script -q logfile command  (macOS/BSD)
-  // script -q -c command logfile (Linux)
-  const isMac = process.platform === 'darwin';
-
-  let scriptArgs;
-  if (isMac) {
-    scriptArgs = ['-q', logFile, shell, '-c', command];
-  } else {
-    scriptArgs = ['-q', '-c', `${shell} -c '${command}'`, logFile];
-  }
-
-  console.log(`Command: script ${scriptArgs.join(' ')}`);
-
-  return new Promise((resolve) => {
-    const child = spawn('script', scriptArgs, {
-      stdio: 'inherit',
-    });
-
-    child.on('exit', (code) => {
-      let output = '';
-      try {
-        output = fs.readFileSync(logFile, 'utf8');
-        console.log(`Captured output: "${output.trim()}"`);
-        fs.unlinkSync(logFile);
-      } catch {
-        console.log('Log file not found');
-      }
-      resolve({ success: code === 0, output });
-    });
-
-    child.on('error', (err) => {
-      console.error(`Error: ${err.message}`);
-      resolve({ success: false, output: '' });
-    });
-  });
-}
-
-// Main
-async function main() {
-  console.log('Screen Output Capture Experiment');
-  console.log('=================================');
-  console.log(`Platform: ${process.platform}`);
-  console.log(
-    `TTY: stdin=${process.stdin.isTTY}, stdout=${process.stdout.isTTY}`
-  );
-
-  if (!isScreenAvailable()) {
-    console.log('Screen is not installed. Exiting.');
-    return;
-  }
-
-  const version = getScreenVersion();
-  console.log(`Screen version: ${version ? version.raw : 'unknown'}`);
-
-  const testCommand = 'echo "hello from screen"';
-
-  // Test 2 is the recommended approach
-  const result = await testDetachedWithLog(testCommand);
-  console.log('\n=== Summary ===');
-  console.log(
-    `Test 2 (detached with log): Success=${result.success}, Output captured=${result.output.includes('hello')}`
-  );
-}
-
-main().catch(console.error);

package/experiments/test-cli.sh

@@ -1,42 +0,0 @@
-#!/bin/bash
-# Test script for start-command CLI
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-CLI_PATH="${SCRIPT_DIR}/../bin/cli.js"
-
-echo "=== Testing start-command CLI ==="
-echo ""
-
-# Test 1: No arguments - should show usage
-echo "Test 1: No arguments (should show usage)"
-node "$CLI_PATH" || true
-echo ""
-
-# Test 2: Successful command
-echo "Test 2: Successful command (echo)"
-node "$CLI_PATH" echo "Hello from test!"
-echo ""
-
-# Test 3: List directory
-echo "Test 3: List directory (ls)"
-node "$CLI_PATH" ls -la "$SCRIPT_DIR"
-echo ""
-
-# Test 4: Failing command (system command)
-echo "Test 4: Failing system command (false) - should NOT detect repository"
-node "$CLI_PATH" false || true
-echo ""
-
-# Test 5: Non-existent command
-echo "Test 5: Non-existent command - should NOT detect repository"
-node "$CLI_PATH" this_command_does_not_exist_xyz123 || true
-echo ""
-
-# Test 6: Check log file creation
-echo "Test 6: Verify log files are created"
-ls -la /tmp/start-command-*.log 2>/dev/null | head -5 || echo "No log files found (unexpected)"
-echo ""
-
-echo "=== All tests completed ==="