Merge pull request #2 from link-foundation/issue-1-025320ceee9d

feat: Implement setProcessName function with cross-platform, multi-runtime support

Author: konard

.changeset/set-process-name-initial.md

@@ -0,0 +1,18 @@
+---
+'set-process-name': minor
+---
+
+Implement setProcessName function with cross-platform and multi-runtime support
+
+- Add setProcessName() async function to set process name visible in system monitoring tools
+- Add setProcessNameSync() synchronous version for simpler use cases
+- Add getProcessName() to retrieve current process name
+- Add getCapabilities() to check platform/runtime capabilities
+- Add detectRuntime() and detectPlatform() utility functions
+- Support Node.js with native process.title (uses libuv prctl internally on Linux)
+- Support Bun with FFI-based prctl for Linux
+- Support Deno with FFI-based prctl for Linux
+- Cross-platform: Linux (prctl), macOS (process.title), Windows (process.title)
+- Include comprehensive test suite (31 tests)
+- Include TypeScript type definitions
+- Include case study documentation

.gitignore

@@ -140,3 +140,6 @@ vite.config.ts.timestamp-*
 
 # jscpd reports
 reports/
+
+# Deno lock file (generated by Deno runtime - not needed for library distribution)
+deno.lock

README.md

@@ -1,196 +1,231 @@
-# js-ai-driven-development-pipeline-template
+# set-process-name
 
-A comprehensive template for AI-driven JavaScript/TypeScript development with full CI/CD pipeline support.
+Cross-platform, multi-runtime library to set the process name visible in system monitoring tools (top, ps, htop, Activity Monitor, Task Manager, etc.).
 
 ## Features
 
-- **Multi-runtime support**: Works with Bun, Node.js, and Deno
-- **Universal testing**: Uses [test-anywhere](https://github.com/link-foundation/test-anywhere) for cross-runtime tests
-- **Automated releases**: Changesets-based versioning with GitHub Actions
-- **Code quality**: ESLint + Prettier with pre-commit hooks via Husky
-- **Package manager agnostic**: Works with bun, npm, yarn, pnpm, and deno
+- **Multi-runtime support**: Works with Node.js, Bun, and Deno
+- **Cross-platform**: Supports Linux, macOS, and Windows
+- **Zero dependencies**: Pure JavaScript with optional FFI for enhanced Linux support
+- **TypeScript support**: Full type definitions included
+- **Comprehensive API**: Async and sync versions, getters, and capability detection
+
+## Installation
+
+```bash
+# npm
+npm install set-process-name
+
+# bun
+bun add set-process-name
+
+# deno
+deno add jsr:@link-foundation/set-process-name
+```
 
 ## Quick Start
 
-### Using This Template
+```javascript
+import { setProcessName } from 'set-process-name';
 
-1. Click "Use this template" on GitHub to create a new repository
-2. Clone your new repository
-3. Update `package.json` with your package name and description
-4. Update the `PACKAGE_NAME` constant in these scripts:
-   - `scripts/validate-changeset.mjs`
-   - `scripts/merge-changesets.mjs`
-   - `scripts/publish-to-npm.mjs`
-   - `scripts/format-release-notes.mjs`
-   - `scripts/create-manual-changeset.mjs`
-5. Install dependencies: `bun install`
-6. Start developing!
+// Set the process name
+await setProcessName('my-app');
 
-### Development
+// Now 'my-app' appears in top, ps, htop instead of 'node' or 'bun'
+```
 
-```bash
-# Install dependencies
-bun install
+## API Reference
 
-# Run tests
-bun test
+### `setProcessName(name: string): Promise<SetProcessNameResult>`
 
-# Or with other runtimes:
-npm test
-deno test --allow-read
+Sets the process name visible in system monitoring tools.
 
-# Lint code
-bun run lint
+```javascript
+import { setProcessName } from 'set-process-name';
 
-# Format code
-bun run format
+const result = await setProcessName('my-service');
 
-# Check all (lint + format + file size)
-bun run check
+console.log(result);
+// {
+//   success: true,
+//   processTitle: true,    // process.title was set successfully
+//   prctl: true,           // prctl was called successfully (Linux only)
+//   runtime: 'node',       // detected runtime
+//   platform: 'linux'      // detected platform
+// }
 ```
 
-## Project Structure
+### `setProcessNameSync(name: string): SetProcessNameResult`
+
+Synchronous version. Note: On Bun runtime, prctl changes may not be applied (use async version for full functionality).
 
+```javascript
+import { setProcessNameSync } from 'set-process-name';
+
+const result = setProcessNameSync('my-service');
 ```
-.
-├── .changeset/           # Changeset configuration
-├── .github/workflows/    # GitHub Actions CI/CD
-├── .husky/               # Git hooks (pre-commit)
-├── examples/             # Usage examples
-├── scripts/              # Build and release scripts
-├── src/                  # Source code
-│   ├── index.js          # Main entry point
-│   └── index.d.ts        # TypeScript definitions
-├── tests/                # Test files
-├── .eslintrc.js          # ESLint configuration
-├── .prettierrc           # Prettier configuration
-├── bunfig.toml           # Bun configuration
-├── deno.json             # Deno configuration
-└── package.json          # Node.js package manifest
+
+### `getProcessName(): string | null`
+
+Gets the current process name from `process.title`.
+
+```javascript
+import { getProcessName, setProcessName } from 'set-process-name';
+
+await setProcessName('my-app');
+console.log(getProcessName()); // 'my-app'
 ```
 
-## Design Choices
+### `getCapabilities(): Capabilities`
+
+Returns information about what features are available on the current platform/runtime.
 
-### Multi-Runtime Support
+```javascript
+import { getCapabilities } from 'set-process-name';
+
+const caps = getCapabilities();
+console.log(caps);
+// {
+//   canSetTitle: true,     // process.title can be set
+//   canSetPrctl: true,     // prctl is available (Linux only)
+//   runtime: 'node',
+//   platform: 'linux'
+// }
+```
 
-This template is designed to work seamlessly with all major JavaScript runtimes:
+### `detectRuntime(): 'node' | 'bun' | 'deno' | 'unknown'`
 
-- **Bun**: Primary runtime with highest performance, uses native test support (`bun test`)
-- **Node.js**: Alternative runtime, uses built-in test runner (`node --test`)
-- **Deno**: Secure runtime with built-in TypeScript support (`deno test`)
+Detects the current JavaScript runtime.
 
-The [test-anywhere](https://github.com/link-foundation/test-anywhere) framework provides a unified testing API that works identically across all runtimes.
+### `detectPlatform(): 'linux' | 'darwin' | 'win32' | 'unknown'`
 
-### Package Manager Agnostic
+Detects the current operating system.
 
-While `package.json` is the source of truth for dependencies, the template supports:
+## Platform-Specific Behavior
 
-- **bun**: Primary choice, uses `bun.lockb`
-- **npm**: Uses `package-lock.json`
-- **yarn**: Uses `yarn.lock`
-- **pnpm**: Uses `pnpm-lock.yaml`
-- **deno**: Uses `deno.json` for configuration
+### Linux
 
-Note: `package-lock.json` is not committed by default to allow any package manager.
+- Uses `process.title` (which internally uses `prctl` via libuv in Node.js)
+- On Bun/Deno: Uses FFI to call `prctl(PR_SET_NAME, name)` directly
+- Name is truncated to 15 characters (Linux kernel limitation for `/proc/<pid>/comm`)
+- Process name visible in `top`, `ps`, `htop`, and `/proc/<pid>/comm`
 
-### Code Quality
+### macOS
 
-- **ESLint**: Configured with recommended rules + Prettier integration
-- **Prettier**: Consistent code formatting
-- **Husky + lint-staged**: Pre-commit hooks ensure code quality
-- **File size limit**: Scripts must stay under 1000 lines for maintainability
+- Uses `process.title` which works via libuv in Node.js
+- Process name visible in Activity Monitor and `ps`
 
-### Release Workflow
+### Windows
 
-The release workflow uses [Changesets](https://github.com/changesets/changesets) for version management:
+- Uses `process.title` for console title
+- Task Manager always shows executable name (cosmetic only)
 
-1. **Creating a changeset**: Run `bun run changeset` to document changes
-2. **PR validation**: CI checks for valid changeset in each PR
-3. **Automated versioning**: Merging to `main` triggers version bump
-4. **npm publishing**: Automated via OIDC trusted publishing (no tokens needed)
-5. **GitHub releases**: Auto-created with formatted release notes
+## Runtime Support
 
-#### Manual Releases
+| Runtime | process.title | prctl (Linux)  |
+| ------- | ------------- | -------------- |
+| Node.js | ✅            | ✅ (via libuv) |
+| Bun     | ✅            | ✅ (via FFI)   |
+| Deno    | ✅            | ✅ (via FFI)   |
 
-Two manual release modes are available via GitHub Actions:
+## Examples
 
-- **Instant release**: Immediately bump version and publish
-- **Changeset PR**: Create a PR with changeset for review
+### Basic Usage
 
-### CI/CD Pipeline
+```javascript
+import { setProcessName, getProcessName } from 'set-process-name';
 
-The GitHub Actions workflow (`.github/workflows/release.yml`) provides:
+async function main() {
+  console.log('Before:', getProcessName()); // 'node'
 
-1. **Changeset check**: Validates PR has exactly one changeset (added by that PR)
-2. **Lint & format**: Ensures code quality standards
-3. **Test matrix**: 3 runtimes × 3 OS = 9 test combinations
-4. **Changeset merge**: Combines multiple pending changesets at release time
-5. **Release**: Automated versioning and npm publishing
+  await setProcessName('my-daemon');
 
-#### Robust Changeset Handling
+  console.log('After:', getProcessName()); // 'my-daemon'
+}
 
-The CI/CD pipeline is designed to handle concurrent PRs gracefully:
+main();
+```
 
-- **PR Validation**: Only validates changesets **added by the current PR**, not pre-existing ones from other merged PRs. This prevents false failures when multiple PRs merge before a release cycle completes.
+### With Capability Check
 
-- **Release-time Merging**: If multiple changesets exist when releasing, they are automatically merged into a single changeset with:
-  - The highest version bump type (major > minor > patch)
-  - All descriptions preserved in chronological order
+```javascript
+import { setProcessName, getCapabilities } from 'set-process-name';
 
-This design decouples PR validation from the need to pull changes from the default branch, reducing conflicts and ensuring that even if CI/CD fails, all unpublished changesets will still get published when the error is resolved.
+const caps = getCapabilities();
 
-## Configuration
+if (caps.canSetPrctl) {
+  console.log('Full Linux prctl support available');
+}
 
-### Updating Package Name
+const result = await setProcessName('worker-1');
 
-After creating a repository from this template, update the package name in:
+if (result.success) {
+  console.log('Process name set successfully');
+} else {
+  console.log('Could not set process name (non-critical)');
+}
+```
 
-1. `package.json`: `"name": "your-package-name"`
-2. `.changeset/config.json`: Package references
-3. Scripts that reference the package name (see Quick Start)
+### CLI Application
 
-### ESLint Rules
+```javascript
+#!/usr/bin/env node
+import { setProcessName } from 'set-process-name';
 
-Customize ESLint in `eslint.config.js`. Current configuration:
+// Set process name at startup
+await setProcessName('my-cli');
 
-- ES Modules support
-- Prettier integration
-- No console restrictions (common in CLI tools)
-- Strict equality enforcement
-- Async/await best practices
-- **Strict unused variables rule**: No exceptions - all unused variables, arguments, and caught errors must be removed (no `_` prefix exceptions)
+// Your CLI code here...
+```
 
-### Prettier Options
+## TypeScript
 
-Configured in `.prettierrc`:
+Full TypeScript support with type definitions:
 
-- Single quotes
-- Semicolons
-- 2-space indentation
-- 80-character line width
-- ES5 trailing commas
-- LF line endings
+```typescript
+import {
+  setProcessName,
+  SetProcessNameResult,
+  Capabilities,
+  Runtime,
+  Platform,
+} from 'set-process-name';
 
-## Scripts Reference
+const result: SetProcessNameResult = await setProcessName('typed-app');
+```
 
-| Script                 | Description                             |
-| ---------------------- | --------------------------------------- |
-| `bun test`             | Run tests with Bun                      |
-| `bun run lint`         | Check code with ESLint                  |
-| `bun run lint:fix`     | Fix ESLint issues automatically         |
-| `bun run format`       | Format code with Prettier               |
-| `bun run format:check` | Check formatting without changing files |
-| `bun run check`        | Run all checks (lint + format)          |
-| `bun run changeset`    | Create a new changeset                  |
+## Testing
 
-## Contributing
+```bash
+# Node.js
+npm test
+
+# Bun
+bun test
+
+# Deno
+deno test --allow-read
+```
 
-1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/my-feature`
-3. Make your changes
-4. Create a changeset: `bun run changeset`
-5. Commit your changes (pre-commit hooks will run automatically)
-6. Push and create a Pull Request
+## How It Works
+
+1. **JavaScript Level**: Sets `process.title` and `process.argv0`
+2. **Node.js**: `process.title` setter uses libuv which internally calls `prctl` on Linux
+3. **Bun/Deno on Linux**: Uses FFI to call `prctl(PR_SET_NAME, name)` directly
+4. **macOS/Windows**: Relies on `process.title` for best-effort support
+
+## Comparison with Alternatives
+
+| Feature            | set-process-name | process-title | process-name |
+| ------------------ | ---------------- | ------------- | ------------ |
+| Set process name   | ✅               | ✅            | ❌           |
+| Linux prctl        | ✅               | ❌            | ❌           |
+| Node.js            | ✅               | ✅            | ✅           |
+| Bun                | ✅               | ❌            | ❌           |
+| Deno               | ✅               | ❌            | ❌           |
+| Zero dependencies  | ✅               | ✅            | ❌           |
+| TypeScript support | ✅               | ❌            | ❌           |
+| Active maintenance | ✅               | ❌            | ❌           |
 
 ## License
 

deno.json

@@ -3,5 +3,6 @@
   "test": {
     "include": ["tests/"],
     "exclude": ["examples/", "node_modules/"]
-  }
+  },
+  "unstable": ["ffi"]
 }