start-command 0.3.1

package/eslint.config.mjs

@@ -0,0 +1,122 @@
+import js from '@eslint/js';
+import prettierConfig from 'eslint-config-prettier';
+import prettierPlugin from 'eslint-plugin-prettier';
+
+export default [
+  js.configs.recommended,
+  prettierConfig,
+  {
+    files: ['**/*.js'],
+    plugins: {
+      prettier: prettierPlugin,
+    },
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'commonjs',
+      globals: {
+        // CommonJS globals
+        require: 'readonly',
+        module: 'readonly',
+        exports: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        // Node.js/Bun globals
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        fetch: 'readonly',
+        Bun: 'readonly',
+      },
+    },
+    rules: {
+      // Prettier integration
+      'prettier/prettier': 'error',
+
+      // Code quality rules
+      'no-unused-vars': 'error',
+      'no-console': 'off', // Allow console in this project
+      'no-debugger': 'error',
+
+      // Best practices
+      eqeqeq: ['error', 'always'],
+      curly: ['error', 'all'],
+      'no-var': 'error',
+      'prefer-const': 'error',
+      'prefer-arrow-callback': 'error',
+      'no-duplicate-imports': 'error',
+
+      // ES6+ features
+      'arrow-body-style': ['error', 'as-needed'],
+      'object-shorthand': ['error', 'always'],
+      'prefer-template': 'error',
+
+      // Async/await
+      'no-async-promise-executor': 'error',
+      'require-await': 'warn',
+
+      // Comments and documentation
+      'spaced-comment': ['error', 'always', { markers: ['/'] }],
+    },
+  },
+  {
+    // ES module files (.mjs)
+    files: ['**/*.mjs'],
+    plugins: {
+      prettier: prettierPlugin,
+    },
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: {
+        // Node.js/Bun globals
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        fetch: 'readonly',
+        Bun: 'readonly',
+      },
+    },
+    rules: {
+      'prettier/prettier': 'error',
+      'no-unused-vars': 'error',
+      'no-console': 'off',
+      'no-debugger': 'error',
+      eqeqeq: ['error', 'always'],
+      curly: ['error', 'all'],
+      'no-var': 'error',
+      'prefer-const': 'error',
+      'prefer-arrow-callback': 'error',
+      'no-duplicate-imports': 'error',
+      'arrow-body-style': ['error', 'as-needed'],
+      'object-shorthand': ['error', 'always'],
+      'prefer-template': 'error',
+      'no-async-promise-executor': 'error',
+      'require-await': 'warn',
+      'spaced-comment': ['error', 'always', { markers: ['/'] }],
+    },
+  },
+  {
+    // Test files and experiments have different requirements
+    files: [
+      'test/**/*.js',
+      'tests/**/*.js',
+      '**/*.test.js',
+      'experiments/**/*.js',
+    ],
+    rules: {
+      'require-await': 'off', // Async functions without await are common in tests
+      'no-unused-vars': 'warn', // Relax for experiments
+    },
+  },
+  {
+    ignores: [
+      'node_modules/**',
+      'coverage/**',
+      'dist/**',
+      '*.min.js',
+      '.eslintcache',
+    ],
+  },
+];

package/experiments/debug-regex.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * 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

@@ -0,0 +1,142 @@
+# 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
+3. **zellij** - Modern, user-friendly multiplexer
+
+### Container Isolation
+
+4. **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`, `zellij`
+- `--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, zellij)
+- 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>'
+```
+
+#### Zellij
+
+```bash
+# Attached
+zellij run -- <command>
+
+# Detached (via layout file or action)
+zellij -s <session> action new-pane -- <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/test-cli.sh

@@ -0,0 +1,42 @@
+#!/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 ==="

package/experiments/test-substitution.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * Test script for the substitution engine
+ * Tests pattern matching with various inputs
+ */
+
+const path = require('path');
+
+// Import the substitution module
+const {
+  parseLinoContent,
+  matchAndSubstitute,
+  loadDefaultSubstitutions,
+  processCommand,
+} = require('../src/lib/substitution');
+
+const testCases = [
+  // NPM install patterns
+  {
+    input: 'install gh-upload-log npm package',
+    expected: 'npm install gh-upload-log',
+    description: 'Basic npm install',
+  },
+  {
+    input: 'install 0.0.1 version of gh-upload-log npm package',
+    expected: 'npm install gh-upload-log@0.0.1',
+    description: 'npm install with version',
+  },
+  {
+    input: 'install lodash npm package globally',
+    expected: 'npm install -g lodash',
+    description: 'Global npm install',
+  },
+  {
+    input: 'install 4.17.21 version of lodash npm package globally',
+    expected: 'npm install -g lodash@4.17.21',
+    description: 'Global npm install with version',
+  },
+  {
+    input: 'uninstall lodash npm package',
+    expected: 'npm uninstall lodash',
+    description: 'npm uninstall',
+  },
+
+  // Git patterns
+  {
+    input: 'clone https://github.com/user/repo repository',
+    expected: 'git clone https://github.com/user/repo',
+    description: 'Git clone with URL',
+  },
+  {
+    input: 'clone git@github.com:user/repo.git repository',
+    expected: 'git clone git@github.com:user/repo.git',
+    description: 'Git clone with SSH URL',
+  },
+  {
+    input: 'checkout main branch',
+    expected: 'git checkout main',
+    description: 'Git checkout branch',
+  },
+  {
+    input: 'create feature-x branch',
+    expected: 'git checkout -b feature-x',
+    description: 'Git create branch',
+  },
+
+  // Common operations
+  {
+    input: 'list files',
+    expected: 'ls -la',
+    description: 'List files',
+  },
+  {
+    input: 'show current directory',
+    expected: 'pwd',
+    description: 'Show working directory',
+  },
+  {
+    input: 'create my-project directory',
+    expected: 'mkdir -p my-project',
+    description: 'Create directory',
+  },
+
+  // Python patterns
+  {
+    input: 'install requests python package',
+    expected: 'pip install requests',
+    description: 'pip install',
+  },
+
+  // Non-matching patterns (should return original)
+  {
+    input: 'echo hello world',
+    expected: 'echo hello world',
+    description: 'Non-matching command (pass through)',
+  },
+  {
+    input: 'npm test',
+    expected: 'npm test',
+    description: 'Regular npm command (pass through)',
+  },
+];
+
+console.log('=== Substitution Engine Tests ===\n');
+
+// Load default substitutions
+const rules = loadDefaultSubstitutions();
+console.log(`Loaded ${rules.length} substitution rules\n`);
+
+let passed = 0;
+let failed = 0;
+
+for (const test of testCases) {
+  const result = matchAndSubstitute(test.input, rules);
+
+  if (result.command === test.expected) {
+    console.log(`✓ PASS: ${test.description}`);
+    console.log(`  Input:    "${test.input}"`);
+    console.log(`  Output:   "${result.command}"`);
+    console.log(
+      `  Matched:  ${result.matched ? result.rule.pattern : 'none (pass through)'}`
+    );
+    passed++;
+  } else {
+    console.log(`✗ FAIL: ${test.description}`);
+    console.log(`  Input:    "${test.input}"`);
+    console.log(`  Expected: "${test.expected}"`);
+    console.log(`  Got:      "${result.command}"`);
+    console.log(`  Matched:  ${result.matched ? result.rule.pattern : 'none'}`);
+    failed++;
+  }
+  console.log('');
+}
+
+console.log('=== Summary ===');
+console.log(`Passed: ${passed}/${testCases.length}`);
+console.log(`Failed: ${failed}/${testCases.length}`);
+
+if (failed > 0) {
+  process.exit(1);
+}
+
+console.log('\n=== All tests passed! ===');

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "start-command",
+  "version": "0.3.1",
+  "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
+  "main": "index.js",
+  "bin": {
+    "$": "./src/bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --test test/",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check:file-size": "node scripts/check-file-size.mjs",
+    "check": "npm run lint && npm run format:check && npm run check:file-size",
+    "prepare": "husky || true",
+    "changeset": "changeset",
+    "changeset:version": "node scripts/changeset-version.mjs",
+    "changeset:publish": "changeset publish",
+    "changeset:status": "changeset status --since=origin/main"
+  },
+  "keywords": [
+    "cli",
+    "command",
+    "gamification",
+    "github",
+    "automation"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/link-foundation/start.git"
+  },
+  "bugs": {
+    "url": "https://github.com/link-foundation/start/issues"
+  },
+  "homepage": "https://github.com/link-foundation/start#readme",
+  "devDependencies": {
+    "@changesets/cli": "^2.29.7",
+    "eslint": "^9.38.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.6",
+    "prettier": "^3.6.2"
+  },
+  "lint-staged": {
+    "*.{js,mjs,cjs}": [
+      "eslint --fix --max-warnings 6",
+      "prettier --write",
+      "prettier --check"
+    ],
+    "*.md": [
+      "prettier --write",
+      "prettier --check"
+    ]
+  }
+}

package/scripts/changeset-version.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+/**
+ * Custom changeset version script that ensures package-lock.json is synchronized
+ * with package.json after version bumps.
+ *
+ * This script:
+ * 1. Runs `changeset version` to update package versions
+ * 2. Runs `npm install` to synchronize package-lock.json with the new versions
+ *
+ * Uses link-foundation libraries:
+ * - use-m: Dynamic package loading without package.json dependencies
+ * - command-stream: Modern shell command execution with streaming support
+ */
+
+// Load use-m dynamically
+const { use } = eval(
+  await (await fetch('https://unpkg.com/use-m/use.js')).text()
+);
+
+// Import command-stream for shell command execution
+const { $ } = await use('command-stream');
+
+try {
+  console.log('Running changeset version...');
+  await $`npx changeset version`;
+
+  console.log('\nSynchronizing package-lock.json...');
+  await $`npm install --package-lock-only`;
+
+  console.log('\n✅ Version bump complete with synchronized package-lock.json');
+} catch (error) {
+  console.error('Error during version bump:', error.message);
+  if (process.env.DEBUG) {
+    console.error('Stack trace:', error.stack);
+  }
+  process.exit(1);
+}

package/scripts/check-file-size.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * Check for files exceeding the maximum allowed line count
+ * Exits with error code 1 if any files exceed the limit
+ */
+
+import { readdir, readFile } from 'fs/promises';
+import { join, relative } from 'path';
+
+const MAX_LINES = 1000;
+const FILE_EXTENSIONS = ['.js', '.mjs', '.cjs'];
+
+/**
+ * Recursively find all JavaScript files in a directory
+ * @param {string} dir - Directory to search
+ * @param {string[]} filesToExclude - Patterns to exclude
+ * @returns {Promise<string[]>} Array of file paths
+ */
+async function findJavaScriptFiles(dir, filesToExclude = []) {
+  const files = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    const relativePath = relative(process.cwd(), fullPath);
+
+    // Skip excluded directories and files
+    if (
+      filesToExclude.some((pattern) =>
+        relativePath.includes(pattern.replace(/\*\*/g, ''))
+      )
+    ) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      files.push(...(await findJavaScriptFiles(fullPath, filesToExclude)));
+    } else if (FILE_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Count lines in a file
+ * @param {string} filePath - Path to the file
+ * @returns {Promise<number>} Number of lines
+ */
+async function countLines(filePath) {
+  const content = await readFile(filePath, 'utf-8');
+  return content.split('\n').length;
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  const excludePatterns = ['node_modules', 'coverage', 'dist', '.git', 'build'];
+
+  console.log(
+    `\nChecking JavaScript files for maximum ${MAX_LINES} lines...\n`
+  );
+
+  const files = await findJavaScriptFiles(process.cwd(), excludePatterns);
+  const violations = [];
+
+  for (const file of files) {
+    const lineCount = await countLines(file);
+    if (lineCount > MAX_LINES) {
+      violations.push({
+        file: relative(process.cwd(), file),
+        lines: lineCount,
+      });
+    }
+  }
+
+  if (violations.length === 0) {
+    console.log('✓ All files are within the line limit\n');
+    process.exit(0);
+  } else {
+    console.error('✗ Found files exceeding the line limit:\n');
+    for (const violation of violations) {
+      console.error(
+        `  ${violation.file}: ${violation.lines} lines (exceeds ${MAX_LINES})`
+      );
+    }
+    console.error(
+      `\nPlease refactor these files to be under ${MAX_LINES} lines\n`
+    );
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error('Error:', error.message);
+  if (process.env.DEBUG) {
+    console.error('Stack trace:', error.stack);
+  }
+  process.exit(1);
+});