start-command 0.25.4 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # start-command
 
+## 0.26.0
+
+### Minor Changes
+
+- 01fbd90: Add `--list` to show all tracked command executions in Links Notation, JSON, or text format.
+
+## 0.25.5
+
+### Patch Changes
+
+- 02527f9: Teach `scripts/create-github-release.mjs` and `scripts/format-github-release.mjs`
+  to honour the `--prefix` argument that both workflows already pass. JavaScript
+  releases are now tagged `js-v<version>` with title `[JavaScript] <version>`,
+  matching the `rust-v<version>` / `[Rust] <version>` convention needed for the
+  mono-repo. Extracted the tag/title construction into `scripts/release-name.mjs`
+  with unit tests in `test/release-name.test.mjs`. See `docs/case-studies/issue-108/`
+  for the full analysis.
+
 ## 0.25.4
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,51 @@
+# start-command — JavaScript package
+
+[![npm version](https://img.shields.io/npm/v/start-command?style=flat)](https://www.npmjs.com/package/start-command)
+[![npm downloads](https://img.shields.io/npm/dm/start-command?style=flat)](https://www.npmjs.com/package/start-command)
+[![JavaScript CI/CD](https://github.com/link-foundation/start/actions/workflows/js.yml/badge.svg)](https://github.com/link-foundation/start/actions/workflows/js.yml)
+[![License: Unlicense](https://img.shields.io/badge/license-Unlicense-blue.svg)](../LICENSE)
+
+JavaScript/Bun implementation of the [`start-command`](../README.md) CLI (`$`).
+
+## Installation
+
+```bash
+bun install -g start-command
+# or, via npm:
+npm install -g start-command
+```
+
+## Usage
+
+```bash
+$ ls -la
+$ npm test
+$ git status
+$ --list
+```
+
+See the project-wide [README](../README.md), [docs/USAGE.md](../docs/USAGE.md),
+and [docs/PIPES.md](../docs/PIPES.md) for the full user-facing guide.
+
+## Development
+
+```bash
+cd js
+bun install
+bun test
+bun run lint
+```
+
+## Releases
+
+JavaScript releases are tagged `js-v<version>` and published to both npm and
+GitHub Releases. The release title carries the `[JavaScript]` prefix, e.g.
+`[JavaScript] 0.25.4`, so JS and Rust releases can be told apart at a glance.
+
+- **Release history**: https://github.com/link-foundation/start/releases?q=%5BJavaScript%5D
+- **CHANGELOG**: [`CHANGELOG.md`](CHANGELOG.md) (per-package changelog generated
+  by [Changesets](https://github.com/changesets/changesets))
+
+## License
+
+Released into the public domain under the [Unlicense](../LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.25.4",
+  "version": "0.26.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {

package/src/bin/cli.js

@@ -31,10 +31,11 @@ const {
 } = require('../lib/user-manager');
 const { handleFailure } = require('../lib/failure-handler');
 const { ExecutionStore, ExecutionRecord } = require('../lib/execution-store');
-const { queryStatus } = require('../lib/status-formatter');
+const { queryStatus, listExecutions } = require('../lib/status-formatter');
 const { printVersion } = require('../lib/version');
 const { createStartBlock, createFinishBlock } = require('../lib/output-blocks');
 const { runWithBunSpawn, runWithNodeSpawn } = require('../lib/spawn-helpers');
+const { printUsage } = require('../lib/usage');
 
 // Configuration from environment variables
 const config = {
@@ -193,6 +194,12 @@ if (wrapperOptions.status) {
   process.exit(0);
 }
 
+// Handle --list flag
+if (wrapperOptions.list) {
+  handleListQuery(wrapperOptions.outputFormat);
+  process.exit(0);
+}
+
 // Handle --cleanup flag
 if (wrapperOptions.cleanup) {
   handleCleanup(wrapperOptions.cleanupDryRun);
@@ -267,6 +274,16 @@ function handleStatusQuery(uuid, outputFormat) {
   }
 }
 
+function handleListQuery(outputFormat) {
+  const result = listExecutions(getExecutionStore(), outputFormat);
+  if (result.success) {
+    console.log(result.output);
+  } else {
+    console.error(`Error: ${result.error}`);
+    process.exit(1);
+  }
+}
+
 /**
  * Handle --cleanup flag
  * Cleans up stale "executing" records (processes that crashed or were killed)
@@ -314,72 +331,6 @@ function handleCleanup(dryRun) {
   }
 }
 
-/** Print usage information */
-function printUsage() {
-  console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>]
-
-Options:
-  --isolated, -i <env>  Run in isolated environment (screen, tmux, docker, ssh)
-  --attached, -a        Run in attached mode (foreground)
-  --detached, -d        Run in detached mode (background)
-  --session, -s <name>  Session name for isolation
-  --session-id <uuid>   Session UUID for tracking (auto-generated if not provided)
-  --session-name <uuid> Alias for --session-id
-  --image <image>       Docker image (required for docker isolation)
-  --endpoint <endpoint> SSH endpoint (required for ssh isolation, e.g., user@host)
-  --isolated-user, -u [name]  Create isolated user with same permissions
-  --keep-user           Keep isolated user after command completes
-  --keep-alive, -k      Keep isolation environment alive after command exits
-  --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 <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
-
-Examples:
-  $ echo "Hello World"
-  $ bun test
-  $ --isolated tmux -- bun start
-  $ -i screen -d bun start
-  $ --isolated docker --image oven/bun:latest -- bun install
-  $ --isolated ssh --endpoint user@remote.server -- ls -la
-  $ --isolated-user -- npm test            # Create isolated user
-  $ -u myuser -- npm start                 # Custom username
-  $ -i screen --isolated-user -- npm test  # Combine with process isolation
-  $ --isolated-user --keep-user -- npm start
-  $ --use-command-stream echo "Hello"      # Use command-stream library`);
-  console.log('');
-  console.log('Piping with $:');
-  console.log('  echo "hi" | $ agent       # Preferred - pipe TO $ command');
-  console.log(
-    '  $ \'echo "hi" | agent\'   # Alternative - quote entire pipeline'
-  );
-  console.log('');
-  console.log('Quoting for special characters:');
-  console.log("  $ 'npm test && npm build' # Wrap for logical operators");
-  console.log("  $ 'cat file > output.txt' # Wrap for redirections");
-  console.log('');
-  console.log('Features:');
-  console.log('  - Logs all output to temporary directory');
-  console.log('  - Displays timestamps and exit codes');
-  console.log(
-    '  - Auto-reports failures for NPM packages (when gh is available)'
-  );
-  console.log('  - Natural language command aliases (via substitutions.lino)');
-  console.log('  - Process isolation via screen, tmux, or docker');
-  console.log('');
-  console.log('Alias examples:');
-  console.log('  $ install lodash npm package           -> npm install lodash');
-  console.log(
-    '  $ install 4.17.21 version of lodash npm package -> npm install lodash@4.17.21'
-  );
-  console.log(
-    '  $ clone https://github.com/user/repo repository -> git clone https://github.com/user/repo'
-  );
-}
-
 /**
  * Run command in isolation mode
  * @param {object} options - Wrapper options

package/src/lib/args-parser.js

@@ -20,7 +20,8 @@
  * --use-command-stream             Use command-stream library for command execution (experimental)
  * --verbose                        Enable verbose/debug output (sets START_VERBOSE=1)
  * --status <uuid>                  Show status of a previous command execution by UUID
- * --output-format <format>         Output format for status (links-notation, json, text)
+ * --list                           List all tracked command executions
+ * --output-format <format>         Output format for status/list (links-notation, json, text)
  * --cleanup                        Clean up stale "executing" records (processes that crashed or were killed)
  * --cleanup-dry-run                Show stale records that would be cleaned up (without actually cleaning)
  */
@@ -169,7 +170,8 @@ function parseArgs(args) {
     shell: 'auto', // Shell to use in isolation environments: auto, bash, zsh, sh
     useCommandStream: false, // Use command-stream library for command execution
     status: null, // UUID to show status for
-    outputFormat: null, // Output format for status (links-notation, json, text)
+    list: false, // List all tracked execution records
+    outputFormat: null, // Output format for status/list (links-notation, json, text)
     cleanup: false, // Clean up stale "executing" records
     cleanupDryRun: false, // Show what would be cleaned without actually cleaning
   };
@@ -434,6 +436,12 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  // --list
+  if (arg === '--list') {
+    options.list = true;
+    return 1;
+  }
+
   // --output-format <format>
   if (arg === '--output-format') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
@@ -656,9 +664,16 @@ function validateOptions(options) {
     }
   }
 
-  // Output format is only valid with --status
-  if (options.outputFormat && !options.status) {
-    throw new Error('--output-format option is only valid with --status');
+  // Single-record and list query modes are mutually exclusive
+  if (options.status && options.list) {
+    throw new Error('Cannot use both --status and --list at the same time');
+  }
+
+  // Output format is only valid with query modes
+  if (options.outputFormat && !options.status && !options.list) {
+    throw new Error(
+      '--output-format option is only valid with --status or --list'
+    );
   }
 
   // Validate shell option

package/src/lib/status-formatter.js

@@ -273,6 +273,86 @@ function formatRecord(record, format) {
   }
 }
 
+function sortRecordsByStartTimeDesc(records) {
+  return [...records].sort(
+    (a, b) => new Date(b.startTime).getTime() - new Date(a.startTime).getTime()
+  );
+}
+
+function indentBlock(block, spaces) {
+  const prefix = ' '.repeat(spaces);
+  return block
+    .split('\n')
+    .map((line) => `${prefix}${line}`)
+    .join('\n');
+}
+
+function prepareRecordForList(record) {
+  return attachCurrentTime(enrichDetachedStatus(record));
+}
+
+/**
+ * Format execution records as a Links Notation list.
+ * @param {Object[]} records - Execution records
+ * @returns {string} Links Notation formatted list
+ */
+function formatRecordListAsLinksNotation(records) {
+  const lines = ['executions', `  count ${records.length}`];
+
+  if (records.length === 0) {
+    lines.push('  records ()');
+    return lines.join('\n');
+  }
+
+  lines.push('  records');
+  for (const record of records) {
+    lines.push(indentBlock(formatRecordAsLinksNotation(record), 4));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format execution records as human-readable text.
+ * @param {Object[]} records - Execution records
+ * @returns {string} Human-readable list
+ */
+function formatRecordListAsText(records) {
+  const lines = ['Executions', `${'='.repeat(50)}`, `Count: ${records.length}`];
+
+  for (const record of records) {
+    lines.push('', formatRecordAsText(record));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format execution records based on format type.
+ * @param {Object[]} records - Execution records
+ * @param {string} format - Output format (links-notation, json, text)
+ * @returns {string} Formatted output string
+ */
+function formatRecordList(records, format) {
+  switch (format) {
+    case 'links-notation':
+      return formatRecordListAsLinksNotation(records);
+    case 'json':
+      return JSON.stringify(
+        {
+          count: records.length,
+          executions: records.map((record) => record.toObject()),
+        },
+        null,
+        2
+      );
+    case 'text':
+      return formatRecordListAsText(records);
+    default:
+      throw new Error(`Unknown output format: ${format}`);
+  }
+}
+
 /**
  * Handle status query and output the result
  * @param {Object} store - ExecutionStore instance
@@ -305,11 +385,39 @@ function queryStatus(store, identifier, outputFormat) {
   }
 }
 
+/**
+ * Handle execution list query and output the result
+ * @param {Object} store - ExecutionStore instance
+ * @param {string|null} outputFormat - Output format (links-notation, json, text)
+ * @returns {{success: boolean, output?: string, error?: string}}
+ */
+function listExecutions(store, outputFormat) {
+  if (!store) {
+    return { success: false, error: 'Execution tracking is disabled.' };
+  }
+
+  try {
+    const records = sortRecordsByStartTimeDesc(
+      store.getAll().map(prepareRecordForList)
+    );
+    return {
+      success: true,
+      output: formatRecordList(records, outputFormat || 'links-notation'),
+    };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}
+
 module.exports = {
   formatRecordAsLinksNotation,
   formatRecordAsText,
   formatRecord,
+  formatRecordListAsLinksNotation,
+  formatRecordListAsText,
+  formatRecordList,
   queryStatus,
+  listExecutions,
   isDetachedSessionAlive,
   enrichDetachedStatus,
   attachCurrentTime,

package/src/lib/usage.js

@@ -0,0 +1,70 @@
+/** Print usage information */
+function printUsage() {
+  console.log(`Usage: $ [options] [--] <command> | $ --status <uuid> [--output-format <fmt>] | $ --list [--output-format <fmt>]
+
+Options:
+  --isolated, -i <env>  Run in isolated environment (screen, tmux, docker, ssh)
+  --attached, -a        Run in attached mode (foreground)
+  --detached, -d        Run in detached mode (background)
+  --session, -s <name>  Session name for isolation
+  --session-id <uuid>   Session UUID for tracking (auto-generated if not provided)
+  --session-name <uuid> Alias for --session-id
+  --image <image>       Docker image (required for docker isolation)
+  --endpoint <endpoint> SSH endpoint (required for ssh isolation, e.g., user@host)
+  --isolated-user, -u [name]  Create isolated user with same permissions
+  --keep-user           Keep isolated user after command completes
+  --keep-alive, -k      Keep isolation environment alive after command exits
+  --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 <id>         Show status of execution by UUID or session name (--output-format: links-notation|json|text)
+  --list                List all tracked executions (--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
+
+Examples:
+  $ echo "Hello World"
+  $ bun test
+  $ --isolated tmux -- bun start
+  $ -i screen -d bun start
+  $ --isolated docker --image oven/bun:latest -- bun install
+  $ --isolated ssh --endpoint user@remote.server -- ls -la
+  $ --isolated-user -- npm test            # Create isolated user
+  $ -u myuser -- npm start                 # Custom username
+  $ -i screen --isolated-user -- npm test  # Combine with process isolation
+  $ --isolated-user --keep-user -- npm start
+  $ --list                                 # List stored execution records
+  $ --list --output-format json            # List stored records as JSON
+  $ --use-command-stream echo "Hello"      # Use command-stream library`);
+  console.log('');
+  console.log('Piping with $:');
+  console.log('  echo "hi" | $ agent       # Preferred - pipe TO $ command');
+  console.log(
+    '  $ \'echo "hi" | agent\'   # Alternative - quote entire pipeline'
+  );
+  console.log('');
+  console.log('Quoting for special characters:');
+  console.log("  $ 'npm test && npm build' # Wrap for logical operators");
+  console.log("  $ 'cat file > output.txt' # Wrap for redirections");
+  console.log('');
+  console.log('Features:');
+  console.log('  - Logs all output to temporary directory');
+  console.log('  - Displays timestamps and exit codes');
+  console.log(
+    '  - Auto-reports failures for NPM packages (when gh is available)'
+  );
+  console.log('  - Natural language command aliases (via substitutions.lino)');
+  console.log('  - Process isolation via screen, tmux, or docker');
+  console.log('');
+  console.log('Alias examples:');
+  console.log('  $ install lodash npm package           -> npm install lodash');
+  console.log(
+    '  $ install 4.17.21 version of lodash npm package -> npm install lodash@4.17.21'
+  );
+  console.log(
+    '  $ clone https://github.com/user/repo repository -> git clone https://github.com/user/repo'
+  );
+}
+
+module.exports = { printUsage };

package/test/args-parser.test.js

@@ -817,13 +817,13 @@ describe('status option', () => {
   it('should throw error for missing UUID argument', () => {
     assert.throws(() => {
       parseArgs(['--status']);
-    }, /requires a UUID argument/);
+    }, /requires a UUID or session name argument/);
   });
 
   it('should throw error for --status with -flag as next argument', () => {
     assert.throws(() => {
       parseArgs(['--status', '--output-format']);
-    }, /requires a UUID argument/);
+    }, /requires a UUID or session name argument/);
   });
 
   it('should default status to null', () => {
@@ -832,6 +832,30 @@ describe('status option', () => {
   });
 });
 
+describe('list option', () => {
+  it('should parse --list flag', () => {
+    const result = parseArgs(['--list']);
+    assert.strictEqual(result.wrapperOptions.list, true);
+    assert.strictEqual(result.command, '');
+  });
+
+  it('should parse --list with JSON output format', () => {
+    const result = parseArgs(['--list', '--output-format', 'json']);
+    assert.strictEqual(result.wrapperOptions.list, true);
+    assert.strictEqual(result.wrapperOptions.outputFormat, 'json');
+  });
+
+  it('should normalize output format with --list', () => {
+    const result = parseArgs(['--list', '--output-format', 'TEXT']);
+    assert.strictEqual(result.wrapperOptions.outputFormat, 'text');
+  });
+
+  it('should default list to false', () => {
+    const result = parseArgs(['echo', 'hello']);
+    assert.strictEqual(result.wrapperOptions.list, false);
+  });
+});
+
 describe('output-format option', () => {
   it('should parse --output-format with --status', () => {
     const uuid = '12345678-1234-1234-1234-123456789abc';
@@ -874,7 +898,7 @@ describe('output-format option', () => {
   it('should throw error for output-format without status', () => {
     assert.throws(() => {
       parseArgs(['--output-format', 'json', '--', 'npm', 'test']);
-    }, /--output-format option is only valid with --status/);
+    }, /--output-format option is only valid with --status or --list/);
   });
 
   it('should accept all valid output formats', () => {

package/test/release-name.test.mjs

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'bun:test';
+import { releaseName, releaseTag } from '../../scripts/release-name.mjs';
+
+describe('releaseTag', () => {
+  it('uses plain "v${version}" when no prefix is given', () => {
+    expect(releaseTag('0.25.4')).toBe('v0.25.4');
+    expect(releaseTag('0.25.4', '')).toBe('v0.25.4');
+  });
+
+  it('prepends known language prefixes', () => {
+    expect(releaseTag('0.25.4', 'js-')).toBe('js-v0.25.4');
+    expect(releaseTag('0.14.0', 'rust-')).toBe('rust-v0.14.0');
+  });
+
+  it('passes arbitrary prefixes through', () => {
+    expect(releaseTag('1.0.0', 'api-')).toBe('api-v1.0.0');
+  });
+});
+
+describe('releaseName', () => {
+  it('returns bare version when prefix is empty (preserves pre-issue-108 behaviour)', () => {
+    expect(releaseName('0.25.4')).toBe('0.25.4');
+    expect(releaseName('0.25.4', '')).toBe('0.25.4');
+  });
+
+  it('decorates known language prefixes with human titles', () => {
+    expect(releaseName('0.25.4', 'js-')).toBe('[JavaScript] 0.25.4');
+    expect(releaseName('0.14.0', 'rust-')).toBe('[Rust] 0.14.0');
+  });
+
+  it('falls back to "${prefix}${version}" for unknown prefixes', () => {
+    expect(releaseName('1.0.0', 'api-')).toBe('api-1.0.0');
+  });
+});

package/test/status-query.test.js

@@ -168,6 +168,77 @@ describe('--status query functionality', () => {
     });
   });
 
+  describe('--list query functionality', () => {
+    it('should output all tracked executions in links-notation format by default', () => {
+      const executingRecord = new ExecutionRecord({
+        command: 'sleep 100',
+        pid: 99999,
+        logPath: '/tmp/executing.log',
+        startTime: '2026-04-24T10:00:00.000Z',
+      });
+      store.save(executingRecord);
+
+      const result = runCli(['--list']);
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toMatch(/^executions\n/);
+      expect(result.stdout).toContain('  count 2');
+      expect(result.stdout).toContain(`    ${testRecord.uuid}`);
+      expect(result.stdout).toContain(`    ${executingRecord.uuid}`);
+      expect(result.stdout).toContain('      command "echo hello world"');
+      expect(result.stdout).toContain('      command "sleep 100"');
+      expect(result.stdout).toContain('      status executed');
+      expect(result.stdout).toContain('      status executing');
+    });
+
+    it('should output all tracked executions in JSON format', () => {
+      const executingRecord = new ExecutionRecord({
+        command: 'sleep 100',
+        pid: 99999,
+        logPath: '/tmp/executing.log',
+      });
+      store.save(executingRecord);
+
+      const result = runCli(['--list', '--output-format', 'json']);
+
+      expect(result.exitCode).toBe(0);
+      const parsed = JSON.parse(result.stdout);
+      expect(parsed.count).toBe(2);
+      expect(parsed.executions.length).toBe(2);
+      expect(parsed.executions.map((record) => record.uuid)).toContain(
+        testRecord.uuid
+      );
+      expect(parsed.executions.map((record) => record.uuid)).toContain(
+        executingRecord.uuid
+      );
+      const executing = parsed.executions.find(
+        (record) => record.uuid === executingRecord.uuid
+      );
+      expect(executing.status).toBe('executing');
+      expect(executing.currentTime).toBeDefined();
+    });
+
+    it('should show count zero when no records are stored', () => {
+      cleanupTestDir();
+
+      const result = runCli(['--list']);
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toMatch(/^executions\n/);
+      expect(result.stdout).toContain('  count 0');
+      expect(result.stdout).toContain('  records ()');
+    });
+
+    it('should show error when tracking is disabled', () => {
+      const result = runCli(['--list'], {
+        START_DISABLE_TRACKING: '1',
+      });
+
+      expect(result.exitCode).toBe(1);
+      expect(result.stderr).toContain('tracking is disabled');
+    });
+  });
+
   describe('executing status', () => {
     it('should show executing status for ongoing commands', () => {
       // Create an executing (not completed) record