start-command 0.13.0 → 0.16.0

package/.github/workflows/release.yml

@@ -1,352 +0,0 @@
-name: Checks and release
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    types: [opened, synchronize, reopened]
-  # Manual release support - consolidated here to work with npm trusted publishing
-  # npm only allows ONE workflow file as trusted publisher, so all publishing
-  # must go through this workflow (release.yml)
-  workflow_dispatch:
-    inputs:
-      release_mode:
-        description: 'Manual release mode'
-        required: true
-        type: choice
-        default: 'instant'
-        options:
-          - instant
-          - changeset-pr
-      bump_type:
-        description: 'Manual release type'
-        required: true
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
-      description:
-        description: 'Manual release description (optional)'
-        required: false
-        type: string
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  # Changeset check - only runs on PRs
-  changeset-check:
-    name: Check for Changesets
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Check for changesets
-        run: |
-          # Skip changeset check for automated version PRs
-          if [[ "${{ github.head_ref }}" == "changeset-release/"* ]]; then
-            echo "Skipping changeset check for automated release PR"
-            exit 0
-          fi
-
-          # Run changeset validation script
-          bun scripts/validate-changeset.mjs
-
-  # Linting and formatting - runs after changeset check on PRs, immediately on main
-  lint:
-    name: Lint and Format Check
-    runs-on: ubuntu-latest
-    needs: [changeset-check]
-    if: always() && (github.event_name == 'push' || needs.changeset-check.result == 'success')
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Run ESLint
-        run: bun run lint
-
-      - name: Check formatting
-        run: bun run format:check
-
-      - name: Check file size limit
-        run: bun scripts/check-file-size.mjs
-
-  # Test with Bun only - 3 OS (Ubuntu, macOS, Windows)
-  test:
-    name: Test (Bun on ${{ matrix.os }})
-    runs-on: ${{ matrix.os }}
-    needs: [changeset-check]
-    if: always() && (github.event_name == 'push' || needs.changeset-check.result == 'success')
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Install screen (Linux)
-        if: runner.os == 'Linux'
-        run: sudo apt-get update && sudo apt-get install -y screen
-
-      - name: Install screen (macOS)
-        if: runner.os == 'macOS'
-        run: brew install screen
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Run tests
-        run: bun test
-
-      # Test both execution modes (default and command-stream)
-      - name: Test default execution mode
-        run: |
-          bun run src/bin/cli.js echo "Testing default mode"
-          echo "Default mode test passed"
-
-      - name: Test command-stream execution mode
-        run: |
-          bun run src/bin/cli.js --use-command-stream echo "Testing command-stream mode"
-          echo "Command-stream mode test passed"
-
-      - name: Test command-stream via env variable
-        env:
-          START_USE_COMMAND_STREAM: '1'
-        run: |
-          bun run src/bin/cli.js echo "Testing env var mode"
-          echo "Env var mode test passed"
-
-      # SSH Integration Tests - Linux only (most reliable for SSH testing)
-      - name: Setup SSH server for integration tests (Linux)
-        if: runner.os == 'Linux'
-        run: |
-          # Install openssh-server if not present
-          sudo apt-get install -y openssh-server
-
-          # Start SSH service
-          sudo systemctl start ssh
-
-          # Generate SSH key without passphrase for testing
-          ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N "" -C "ci-test-key"
-
-          # Add the public key to authorized_keys for passwordless login
-          cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys
-          chmod 600 ~/.ssh/authorized_keys
-
-          # Configure SSH to accept localhost connections without prompts
-          mkdir -p ~/.ssh
-          cat >> ~/.ssh/config << 'EOF'
-          Host localhost
-            StrictHostKeyChecking no
-            UserKnownHostsFile /dev/null
-            LogLevel ERROR
-          EOF
-          chmod 600 ~/.ssh/config
-
-          # Test SSH connectivity
-          ssh localhost "echo 'SSH connection successful'"
-
-      - name: Run SSH integration tests (Linux)
-        if: runner.os == 'Linux'
-        run: bun test test/ssh-integration.test.js
-
-  # Release - only runs on main after tests pass (for push events)
-  release:
-    name: Release
-    needs: [lint, test]
-    # Use always() to ensure this job runs even if changeset-check was skipped
-    # This is needed because lint/test jobs have a transitive dependency on changeset-check
-    if: always() && github.ref == 'refs/heads/main' && github.event_name == 'push' && needs.lint.result == 'success' && needs.test.result == 'success'
-    runs-on: ubuntu-latest
-    # Permissions required for npm OIDC trusted publishing
-    permissions:
-      contents: write
-      pull-requests: write
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Setup Node.js for npm publishing
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Update npm for OIDC trusted publishing
-        run: bun scripts/setup-npm.mjs
-
-      - name: Check for changesets
-        id: check_changesets
-        run: |
-          # Count changeset files (excluding README.md and config.json)
-          CHANGESET_COUNT=$(find .changeset -name "*.md" ! -name "README.md" | wc -l)
-          echo "Found $CHANGESET_COUNT changeset file(s)"
-          echo "has_changesets=$([[ $CHANGESET_COUNT -gt 0 ]] && echo 'true' || echo 'false')" >> $GITHUB_OUTPUT
-
-      - name: Version packages and commit to main
-        if: steps.check_changesets.outputs.has_changesets == 'true'
-        id: version
-        run: bun scripts/version-and-commit.mjs --mode changeset
-
-      - name: Publish to npm
-        # Run if version was committed OR if a previous attempt already committed (for re-runs)
-        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
-        id: publish
-        run: bun scripts/publish-to-npm.mjs --should-pull
-
-      - name: Create GitHub Release
-        if: steps.publish.outputs.published == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: bun scripts/create-github-release.mjs --release-version "${{ steps.publish.outputs.published_version }}" --repository "${{ github.repository }}"
-
-      - name: Format GitHub release notes
-        if: steps.publish.outputs.published == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: bun scripts/format-github-release.mjs --release-version "${{ steps.publish.outputs.published_version }}" --repository "${{ github.repository }}" --commit-sha "${{ github.sha }}"
-
-  # Manual Instant Release - triggered via workflow_dispatch with instant mode
-  # This job is in release.yml because npm trusted publishing
-  # only allows one workflow file to be registered as a trusted publisher
-  instant-release:
-    name: Instant Release
-    if: github.event_name == 'workflow_dispatch' && github.event.inputs.release_mode == 'instant'
-    runs-on: ubuntu-latest
-    # Permissions required for npm OIDC trusted publishing
-    permissions:
-      contents: write
-      pull-requests: write
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Setup Node.js for npm publishing
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Update npm for OIDC trusted publishing
-        run: bun scripts/setup-npm.mjs
-
-      - name: Version packages and commit to main
-        id: version
-        run: bun scripts/version-and-commit.mjs --mode instant --bump-type "${{ github.event.inputs.bump_type }}" --description "${{ github.event.inputs.description }}"
-
-      - name: Publish to npm
-        # Run if version was committed OR if a previous attempt already committed (for re-runs)
-        if: steps.version.outputs.version_committed == 'true' || steps.version.outputs.already_released == 'true'
-        id: publish
-        run: bun scripts/publish-to-npm.mjs
-
-      - name: Create GitHub Release
-        if: steps.publish.outputs.published == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: bun scripts/create-github-release.mjs --release-version "${{ steps.publish.outputs.published_version }}" --repository "${{ github.repository }}"
-
-      - name: Format GitHub release notes
-        if: steps.publish.outputs.published == 'true'
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: bun scripts/format-github-release.mjs --release-version "${{ steps.publish.outputs.published_version }}" --repository "${{ github.repository }}" --commit-sha "${{ github.sha }}"
-
-  # Manual Changeset PR - creates a pull request with the changeset for review
-  changeset-pr:
-    name: Create Changeset PR
-    if: github.event_name == 'workflow_dispatch' && github.event.inputs.release_mode == 'changeset-pr'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Create changeset file
-        run: bun scripts/create-manual-changeset.mjs --bump-type "${{ github.event.inputs.bump_type }}" --description "${{ github.event.inputs.description }}"
-
-      - name: Format changeset with Prettier
-        run: |
-          # Run Prettier on the changeset file to ensure it matches project style
-          bun x prettier --write ".changeset/*.md" || true
-
-          echo "Formatted changeset files"
-
-      - name: Create Pull Request
-        uses: peter-evans/create-pull-request@v7
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          commit-message: 'chore: add changeset for manual ${{ github.event.inputs.bump_type }} release'
-          branch: changeset-manual-release-${{ github.run_id }}
-          delete-branch: true
-          title: 'chore: manual ${{ github.event.inputs.bump_type }} release'
-          body: |
-            ## Manual Release Request
-
-            This PR was created by a manual workflow trigger to prepare a **${{ github.event.inputs.bump_type }}** release.
-
-            ### Release Details
-            - **Type:** ${{ github.event.inputs.bump_type }}
-            - **Description:** ${{ github.event.inputs.description || 'Manual release' }}
-            - **Triggered by:** @${{ github.actor }}
-
-            ### Next Steps
-            1. Review the changeset in this PR
-            2. Merge this PR to main
-            3. The automated release workflow will create a version PR
-            4. Merge the version PR to publish to npm and create a GitHub release

package/.husky/pre-commit

@@ -1 +0,0 @@
-npx lint-staged

package/ARCHITECTURE.md

@@ -1,297 +0,0 @@
-# Architecture
-
-This document describes the architecture of the `$` command (start-command).
-
-## Overview
-
-The start-command is a CLI tool that wraps shell commands to provide automatic logging, error reporting, natural language aliases, and process isolation capabilities.
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         User Command                                 │
-│                    $ [options] command [args]                        │
-└──────────────────────────────┬──────────────────────────────────────┘
-                               │
-                               ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                         CLI Entry Point                              │
-│                        src/bin/cli.js                                │
-├─────────────────────────────────────────────────────────────────────┤
-│  • Parse command line arguments                                      │
-│  • Handle --version, --help flags                                    │
-│  • Route to isolation or direct execution                           │
-└──────────────────────────────┬──────────────────────────────────────┘
-                               │
-              ┌────────────────┴────────────────┐
-              │                                 │
-              ▼                                 ▼
-┌─────────────────────────┐      ┌─────────────────────────────────────┐
-│   Direct Execution      │      │     Isolated Execution              │
-│   (no --isolated)       │      │     (--isolated screen/tmux/docker) │
-├─────────────────────────┤      ├─────────────────────────────────────┤
-│ • Spawn shell process   │      │ src/lib/isolation.js                │
-│ • Capture stdout/stderr │      │ • runInScreen()                     │
-│ • Log to temp file      │      │ • runInTmux()                       │
-│ • Report failures       │      │ • runInDocker()                     │
-└─────────────────────────┘      └─────────────────────────────────────┘
-```
-
-## Core Modules
-
-### 1. CLI Entry Point (`src/bin/cli.js`)
-
-The main entry point that:
-
-- Parses command line arguments using `args-parser.js`
-- Processes command substitutions using `substitution.js`
-- Routes execution to direct mode or isolation mode
-- Handles logging and error reporting
-
-### 2. Argument Parser (`src/lib/args-parser.js`)
-
-Parses wrapper options and extracts the command to execute:
-
-```javascript
-{
-  isolated: null,     // 'screen' | 'tmux' | 'docker' | null
-  attached: false,    // Run in attached/foreground mode
-  detached: false,    // Run in detached/background mode
-  session: null,      // Custom session name
-  image: null,        // Docker image name
-  keepAlive: false,   // Keep environment alive after command exits
-}
-```
-
-### 3. Substitution Engine (`src/lib/substitution.js`)
-
-Provides natural language command aliases:
-
-- Loads patterns from `substitutions.lino`
-- Matches user input against patterns with variables
-- Returns substituted command or original if no match
-
-### 4. Isolation Module (`src/lib/isolation.js`)
-
-Handles process isolation in terminal multiplexers and containers:
-
-```
-┌────────────────────────────────────────────────────────────┐
-│                    runIsolated()                            │
-│              (dispatcher function)                          │
-└───────────────┬───────────────┬───────────────┬────────────┘
-                │               │               │
-        ┌───────▼───────┐ ┌─────▼─────┐ ┌───────▼───────┐
-        │  runInScreen  │ │runInTmux  │ │ runInDocker   │
-        │               │ │           │ │               │
-        │ GNU Screen    │ │ tmux      │ │ Docker        │
-        │ multiplexer   │ │ terminal  │ │ containers    │
-        └───────────────┘ └───────────┘ └───────────────┘
-```
-
-## Isolation Architecture
-
-### Execution Modes
-
-| Mode         | Description                                 | Default Behavior               |
-| ------------ | ------------------------------------------- | ------------------------------ |
-| Attached     | Command runs in foreground, interactive     | Session exits after completion |
-| Detached     | Command runs in background                  | Session exits after completion |
-| + Keep-Alive | Session stays alive after command completes | Requires `--keep-alive` flag   |
-
-### Auto-Exit Behavior
-
-By default, all isolation environments automatically exit after command completion:
-
-```
-┌───────────────────────────────────────────────────────────────┐
-│                    Default (keepAlive=false)                  │
-├───────────────────────────────────────────────────────────────┤
-│  1. Start isolation environment                               │
-│  2. Execute command                                           │
-│  3. Capture output (if attached mode)                         │
-│  4. Environment exits automatically                           │
-│  5. Resources freed                                           │
-└───────────────────────────────────────────────────────────────┘
-
-┌───────────────────────────────────────────────────────────────┐
-│                    With --keep-alive                          │
-├───────────────────────────────────────────────────────────────┤
-│  1. Start isolation environment                               │
-│  2. Execute command                                           │
-│  3. Command completes                                         │
-│  4. Shell stays running in session                           │
-│  5. User can reattach and interact                           │
-└───────────────────────────────────────────────────────────────┘
-```
-
-### Screen Isolation
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     Screen Execution Flow                        │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  Attached Mode:                                                  │
-│  ┌─────────────────────────────────────────────────────────┐    │
-│  │ Uses detached mode with log capture internally           │    │
-│  │ • Start: screen -dmS <session> -L -Logfile <log>        │    │
-│  │ • Poll for session completion                            │    │
-│  │ • Read and display captured output                       │    │
-│  │ • Clean up log file                                      │    │
-│  └─────────────────────────────────────────────────────────┘    │
-│                                                                  │
-│  Detached Mode:                                                  │
-│  ┌─────────────────────────────────────────────────────────┐    │
-│  │ • Without keep-alive: screen -dmS <session> sh -c cmd   │    │
-│  │ • With keep-alive: screen -dmS <session> sh -c "cmd; sh"│    │
-│  └─────────────────────────────────────────────────────────┘    │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### tmux Isolation
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                      tmux Execution Flow                         │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  Attached Mode:                                                  │
-│  ┌─────────────────────────────────────────────────────────┐    │
-│  │ • tmux new-session -s <session> <command>               │    │
-│  │ • Interactive, exits when command completes             │    │
-│  └─────────────────────────────────────────────────────────┘    │
-│                                                                  │
-│  Detached Mode:                                                  │
-│  ┌─────────────────────────────────────────────────────────┐    │
-│  │ • Without keep-alive: tmux new-session -d -s <session>  │    │
-│  │ • With keep-alive: command followed by shell exec       │    │
-│  └─────────────────────────────────────────────────────────┘    │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Docker Isolation
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     Docker Execution Flow                        │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  Attached Mode:                                                  │
-│  ┌─────────────────────────────────────────────────────────┐    │
-│  │ • docker run -it --rm --name <name> <image> sh -c cmd   │    │
-│  │ • Interactive, container auto-removed on exit           │    │
-│  └─────────────────────────────────────────────────────────┘    │
-│                                                                  │
-│  Detached Mode:                                                  │
-│  ┌─────────────────────────────────────────────────────────┐    │
-│  │ • Without keep-alive: docker run -d --name <name> ...   │    │
-│  │ • With keep-alive: command followed by shell exec       │    │
-│  └─────────────────────────────────────────────────────────┘    │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Logging Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                       Logging Flow                               │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  ┌─────────────┐    ┌──────────────┐    ┌───────────────────┐   │
-│  │ Command     │───▶│ Capture      │───▶│ Write to          │   │
-│  │ Execution   │    │ stdout/stderr│    │ Temp Log File     │   │
-│  └─────────────┘    └──────────────┘    └───────────────────┘   │
-│                                                                  │
-│  Log File Format:                                                │
-│  ┌─────────────────────────────────────────────────────────┐    │
-│  │ === Start Command Log ===                                │    │
-│  │ Timestamp: 2024-01-15 10:30:45                          │    │
-│  │ Command: <command>                                       │    │
-│  │ Shell: /bin/bash                                        │    │
-│  │ Platform: linux                                          │    │
-│  │ ==================================================      │    │
-│  │ <command output>                                         │    │
-│  │ ==================================================      │    │
-│  │ Finished: 2024-01-15 10:30:46                           │    │
-│  │ Exit Code: 0                                             │    │
-│  └─────────────────────────────────────────────────────────┘    │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## File Structure
-
-```
-start-command/
-├── src/
-│   ├── bin/
-│   │   └── cli.js              # Main entry point
-│   └── lib/
-│       ├── args-parser.js      # Argument parsing
-│       ├── isolation.js        # Isolation backends
-│       ├── substitution.js     # Command aliases
-│       └── substitutions.lino  # Alias patterns
-├── test/
-│   ├── cli.test.js            # CLI tests
-│   ├── isolation.test.js      # Isolation tests
-│   ├── args-parser.test.js    # Parser tests
-│   └── substitution.test.js   # Substitution tests
-├── docs/
-│   ├── PIPES.md               # Piping documentation
-│   └── USAGE.md               # Usage examples
-├── experiments/               # Experimental scripts
-├── REQUIREMENTS.md            # Requirements specification
-├── ARCHITECTURE.md            # This file
-└── README.md                  # Project overview
-```
-
-## Design Decisions
-
-### 1. Auto-Exit by Default
-
-All isolation environments exit automatically after command completion to:
-
-- Prevent resource leaks from orphaned sessions
-- Ensure consistent behavior across backends
-- Match user expectations for command execution
-
-### 2. Log Capture in Attached Screen Mode
-
-Screen's attached mode uses internal detached mode with log capture because:
-
-- Direct attached mode loses output for quick commands
-- Screen's virtual terminal is destroyed before output is visible
-- Log capture ensures reliable output preservation
-
-### 3. Keep-Alive as Opt-In
-
-The `--keep-alive` flag is disabled by default because:
-
-- Most use cases don't require persistent sessions
-- Prevents accidental resource consumption
-- Explicit opt-in for advanced workflows
-
-### 4. Uniform Backend Interface
-
-All isolation backends share a consistent interface:
-
-```javascript
-async function runInBackend(command, options) {
-  return {
-    success: boolean,
-    sessionName: string,
-    message: string,
-    exitCode?: number,
-    output?: string
-  };
-}
-```
-
-This enables:
-
-- Easy addition of new backends
-- Consistent error handling
-- Unified logging format

package/LICENSE

@@ -1,24 +0,0 @@
-This is free and unencumbered software released into the public domain.
-
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
-
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
-For more information, please refer to <https://unlicense.org>