start-command 0.3.1

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.changeset/isolation-support.md

@@ -0,0 +1,30 @@
+---
+'start-command': minor
+---
+
+Add process isolation support with --isolated option
+
+This release adds the ability to run commands in isolated environments:
+
+**New Features:**
+
+- `--isolated` / `-i` option to run commands in screen, tmux, zellij, or docker
+- `--attached` / `-a` and `--detached` / `-d` modes for foreground/background execution
+- `--session` / `-s` option for custom session names
+- `--image` option for Docker container image specification
+- Two command syntax patterns: `$ [options] -- [command]` or `$ [options] command`
+
+**Supported Backends:**
+
+- GNU Screen - classic terminal multiplexer
+- tmux - modern terminal multiplexer
+- zellij - modern terminal workspace
+- Docker - container isolation
+
+**Examples:**
+
+```bash
+$ --isolated tmux -- npm start
+$ -i screen -d npm start
+$ --isolated docker --image node:20 -- npm install
+```

package/.github/workflows/release.yml

@@ -0,0 +1,292 @@
+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 dependencies
+        run: bun install
+
+      - name: Run tests
+        run: bun test
+
+  # 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

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

package/.prettierignore

@@ -0,0 +1,6 @@
+node_modules
+coverage
+dist
+*.min.js
+package-lock.json
+.eslintcache

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# start-command
+
+## 0.3.1
+
+### Patch Changes
+
+- 6a701da: Apply js-ai-driven-development-pipeline-template (Bun-only)
+  - Add .changeset/ for version management
+  - Add .husky/ for git hooks
+  - Add eslint.config.mjs with ESLint 9 flat config
+  - Add .prettierrc for code formatting
+  - Add bunfig.toml for Bun configuration
+  - Add scripts/ directory with release automation scripts
+  - Create release.yml workflow (Bun-only, merged test.yml)
+  - Add CHANGELOG.md
+
+## 0.3.0
+
+### Minor Changes
+
+- Initial release with natural language command aliases
+- Automatic logging of all commands
+- Auto-reporting on failure for NPM packages
+- GitHub integration for issue creation

package/LICENSE

@@ -0,0 +1,24 @@
+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>

package/README.md

@@ -0,0 +1,249 @@
+# start-command (`$`)
+
+Gamification of coding - execute any command with automatic logging and ability to auto-report issues on GitHub.
+
+## Installation
+
+```bash
+npm install -g start-command
+```
+
+## Usage
+
+The `$` command acts as a wrapper for any shell command:
+
+```bash
+$ ls -la
+$ cat file.txt
+$ npm test
+$ git status
+```
+
+### Natural Language Commands (Aliases)
+
+You can also use natural language to execute common commands. The `$` command supports pattern-based substitutions defined in `substitutions.lino`:
+
+```bash
+# Install NPM packages
+$ install lodash npm package                    # -> npm install lodash
+$ install 4.17.21 version of lodash npm package # -> npm install lodash@4.17.21
+$ install lodash npm package globally           # -> npm install -g lodash
+
+# Clone repositories
+$ clone https://github.com/user/repo repository # -> git clone https://github.com/user/repo
+
+# Git operations
+$ checkout main branch                          # -> git checkout main
+$ create feature-x branch                       # -> git checkout -b feature-x
+
+# Common operations
+$ list files                                    # -> ls -la
+$ show current directory                        # -> pwd
+$ create my-project directory                   # -> mkdir -p my-project
+
+# Python packages
+$ install requests python package               # -> pip install requests
+```
+
+If no pattern matches, the command is executed as-is.
+
+## Features
+
+### Natural Language Aliases (Links Notation)
+
+Commands can be expressed in plain English using patterns defined in `substitutions.lino`. This file uses [Links Notation](https://github.com/link-foundation/links-notation) style patterns with variables.
+
+Each pattern is defined as a doublet link - a pair of pattern and replacement wrapped in parentheses:
+
+```
+# Pattern definition in substitutions.lino:
+(
+  install $packageName npm package
+  npm install $packageName
+)
+
+# Usage:
+$ install express npm package
+# Executes: npm install express
+```
+
+Variables like `$packageName`, `$version`, `$repository` are captured and used in the substitution.
+
+### Automatic Logging
+
+All command output is automatically saved to your system's temporary directory with timestamps:
+
+```
+[2024-01-15 10:30:45.123] Starting: npm test
+... command output ...
+[2024-01-15 10:30:52.456] Finished
+Exit code: 0
+Log saved: /tmp/start-command-1705312245123-abc123.log
+```
+
+### Exit Code Display
+
+The exit code is always prominently displayed after command completion, making it clear whether the command succeeded or failed.
+
+### Auto-Reporting on Failure (NPM packages)
+
+When a command fails (non-zero exit code) and it's a globally installed NPM package:
+
+1. **Repository Detection** - Automatically detects the GitHub repository for NPM packages
+2. **Log Upload** - Uploads the full log to GitHub (requires [gh-upload-log](https://github.com/link-foundation/gh-upload-log))
+3. **Issue Creation** - Creates an issue in the package's repository with:
+   - Command that was executed
+   - Exit code
+   - System information
+   - Link to uploaded log
+
+```
+[2024-01-15 10:30:45.123] Starting: some-npm-tool --broken-arg
+... error output ...
+[2024-01-15 10:30:46.789] Finished
+Exit code: 1
+Log saved: /tmp/start-command-1705312246789-def456.log
+
+Detected repository: https://github.com/owner/some-npm-tool
+Log uploaded: https://gist.github.com/user/abc123
+Issue created: https://github.com/owner/some-npm-tool/issues/42
+```
+
+### Process Isolation
+
+Run commands in isolated environments using terminal multiplexers or containers:
+
+```bash
+# Run in tmux (attached by default)
+$ --isolated tmux -- npm start
+
+# Run in screen detached
+$ --isolated screen --detached -- npm start
+
+# Run in docker container
+$ --isolated docker --image node:20 -- npm install
+
+# Short form with custom session name
+$ -i tmux -s my-session -d npm start
+```
+
+#### Supported Backends
+
+| Backend  | Description                            | Installation                                               |
+| -------- | -------------------------------------- | ---------------------------------------------------------- |
+| `screen` | GNU Screen terminal multiplexer        | `apt install screen` / `brew install screen`               |
+| `tmux`   | Modern terminal multiplexer            | `apt install tmux` / `brew install tmux`                   |
+| `zellij` | Modern terminal workspace              | `cargo install zellij` / `brew install zellij`             |
+| `docker` | Container isolation (requires --image) | [Docker Installation](https://docs.docker.com/get-docker/) |
+
+#### Isolation Options
+
+| Option           | Description                                      |
+| ---------------- | ------------------------------------------------ |
+| `--isolated, -i` | Isolation backend (screen, tmux, docker, zellij) |
+| `--attached, -a` | Run in attached/foreground mode (default)        |
+| `--detached, -d` | Run in detached/background mode                  |
+| `--session, -s`  | Custom session/container name                    |
+| `--image`        | Docker image (required for docker isolation)     |
+
+**Note:** Using both `--attached` and `--detached` together will result in an error - you must choose one mode.
+
+### Graceful Degradation
+
+The tool works in any environment:
+
+- **No `gh` CLI?** - Logs are still saved locally, auto-reporting is skipped
+- **No `gh-upload-log`?** - Issue can still be created with local log reference
+- **Repository not detected?** - Command runs normally with logging
+- **No permission to create issue?** - Skipped with a clear message
+- **Isolation backend not installed?** - Clear error message with installation instructions
+
+## Requirements
+
+### Required
+
+- Node.js >= 14.0.0
+
+### Optional (for full auto-reporting)
+
+- [GitHub CLI (`gh`)](https://cli.github.com/) - For authentication and issue creation
+- [gh-upload-log](https://github.com/link-foundation/gh-upload-log) - For uploading log files
+
+To set up auto-reporting:
+
+```bash
+# Install GitHub CLI and authenticate
+gh auth login
+
+# Install log uploader
+npm install -g gh-upload-log
+```
+
+## How It Works
+
+1. **Command Execution** - Your command is passed directly to the shell (bash/powershell/sh)
+2. **Output Capture** - Both stdout and stderr are captured while still being displayed
+3. **Log File** - Complete output is saved with timestamps and system info
+4. **Failure Handling** - On non-zero exit:
+   - Detects if the command is an NPM package
+   - Looks up the package's GitHub repository
+   - Uploads log (if `gh-upload-log` is available)
+   - Creates an issue (if `gh` is authenticated and has permission)
+
+## Configuration
+
+The following environment variables can be used to customize behavior:
+
+| Variable                      | Description                                                    |
+| ----------------------------- | -------------------------------------------------------------- |
+| `START_DISABLE_AUTO_ISSUE`    | Set to `1` or `true` to disable automatic issue creation       |
+| `START_DISABLE_LOG_UPLOAD`    | Set to `1` or `true` to disable log upload                     |
+| `START_LOG_DIR`               | Custom directory for log files (defaults to OS temp directory) |
+| `START_VERBOSE`               | Set to `1` or `true` for verbose output                        |
+| `START_DISABLE_SUBSTITUTIONS` | Set to `1` or `true` to disable pattern matching/aliases       |
+| `START_SUBSTITUTIONS_PATH`    | Custom path to substitutions.lino file                         |
+
+Example:
+
+```bash
+# Run without auto-issue creation
+START_DISABLE_AUTO_ISSUE=1 $ npm test
+
+# Use custom log directory
+START_LOG_DIR=./logs $ npm test
+
+# Disable substitutions (use raw command)
+START_DISABLE_SUBSTITUTIONS=1 $ install lodash npm package
+
+# Use custom substitutions file
+START_SUBSTITUTIONS_PATH=/path/to/my-rules.lino $ install mypackage npm package
+```
+
+### Custom Substitutions
+
+You can create your own substitution patterns by placing a `substitutions.lino` file in `~/.start-command/substitutions.lino`. User patterns take precedence over the default ones.
+
+## Log File Format
+
+Log files are saved as `start-command-{timestamp}-{random}.log` and contain:
+
+```
+=== Start Command Log ===
+Timestamp: 2024-01-15 10:30:45.123
+Command: npm test
+Shell: /bin/bash
+Platform: linux
+Node Version: v18.17.0
+Working Directory: /home/user/project
+==================================================
+
+... command output ...
+
+==================================================
+Finished: 2024-01-15 10:30:52.456
+Exit Code: 0
+```
+
+## License
+
+MIT