@osdlc/command-seam 0.0.1-stage → 0.4.1

package/CHANGELOG.md

@@ -1,55 +1,50 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/),
-and this project adheres to [Semantic Versioning](https://semver.org/).
-
-## [0.4.0] - 2026-10-16
-
-The package is renamed, and the repository moved from `sksizer/sdlc` to
-[osdlc/osdlc](https://github.com/osdlc/osdlc).
-
-### Breaking
-
-- The package is now `@osdlc/command-seam`, renamed from
-  `@sksizer/command-seam`. To move, replace `@sksizer/command-seam` with
-  `@osdlc/command-seam` in `package.json` and in every import, including
-  `@osdlc/command-seam/testing`. `@sksizer/command-seam` gets no further
-  releases.
-
-### Added
-
-These exports are experimental (see the README's Stability section).
-
-- `installGroupSignalForwarding(opts?)`, with options type
-  `GroupSignalForwardingOptions`: opt-in. While a group started with
-  `processGroup: true` (async and managed runners) is live, `SIGINT`,
-  `SIGTERM` and `SIGHUP` send `SIGTERM` to every group, `SIGKILL` after
-  `graceMs` (default 1000), then exit with `128 + signal number`. A repeat
-  signal escalates to `SIGKILL` at once; an `exit` handler `SIGKILL`s groups
-  whose run is still in flight. Listeners are attached only while a group is
-  starting or live, ahead of the host's own. A host with its own listener, `process.once`
-  included, keeps the exit; its groups still get `SIGKILL` after `graceMs`, or
-  on exit if sooner and the run is in flight. Returns an uninstall function.
-  POSIX only; a no-op on Windows. `SIGKILL` of the host still orphans its groups. When
-  forwarding owns the exit, a new `processGroup: true` run after the first
-  forwarded signal is refused: it starts nothing and settles with
-  `reason: 'abort'`. The uninstall function resets this.
-- `forwardedSignal()`: the signal forwarded when forwarding owns the exit, or
-  `undefined`. A host that runs one command after another checks it to stop.
-- `forwardedExitCode()`: `128 + signal number` for `forwardedSignal()`, or
-  `undefined`. A host that sets its own exit code keeps this one over it.
-- `liveProcessGroups()`: the pids of the groups currently registered. A group
-  stays registered until it is empty, also after its run settles or its
-  leader exits, so a forwarded signal still kills a background member or one
-  waiting for the `SIGKILL` follow-up. The host's normal exit kills only the
-  groups whose run is still in flight, so a daemon a settled run left behind
-  keeps running.
-- `unref` on the managed-process runner's options: the parent can exit while
-  the (usually `processGroup`) child keeps running. Such a group is not tracked
-  by `installGroupSignalForwarding`: a signal to the parent does not reach it
-  and the parent's exit does not `SIGKILL` it.
+## 0.4.1
+
+### Patch Changes
+
+- 4fa373f: The npm package no longer contains `smoke.mjs`. It was a check for this
+  repository's CI, not part of the API.
+
+## 0.4.0
+
+### Minor Changes
+
+- e30f155: **Breaking:** the package is now `@osdlc/command-seam`, renamed from `@sksizer/command-seam`. The repository moved from `sksizer/sdlc` to [osdlc/osdlc](https://github.com/osdlc/osdlc).
+  
+  To move, replace `@sksizer/command-seam` with `@osdlc/command-seam` in `package.json` and in every import, including `@osdlc/command-seam/testing`. `@sksizer/command-seam` gets no further releases.
+- e30f155: Add process-group signal forwarding and `unref` on the managed-process runner. These exports are experimental (see the README's Stability section).
+  
+  - `installGroupSignalForwarding(opts?)`, with options type
+    `GroupSignalForwardingOptions`: opt-in. While a group started with
+    `processGroup: true` (async and managed runners) is live, `SIGINT`,
+    `SIGTERM` and `SIGHUP` send `SIGTERM` to every group, `SIGKILL` after
+    `graceMs` (default 1000), then exit with `128 + signal number`. A repeat
+    signal escalates to `SIGKILL` at once; an `exit` handler `SIGKILL`s groups
+    whose run is still in flight. Listeners are attached only while a group is
+    starting or live, ahead of the host's own. A host with its own listener,
+    `process.once` included, keeps the exit; its groups still get `SIGKILL`
+    after `graceMs`, or on exit if sooner and the run is in flight. Returns an
+    uninstall function. POSIX only; a no-op on Windows. `SIGKILL` of the host
+    still orphans its groups. When forwarding owns the exit, a new
+    `processGroup: true` run after the first forwarded signal is refused: it
+    starts nothing and settles with `reason: 'abort'`. The uninstall function
+    resets this.
+  - `forwardedSignal()`: the signal forwarded when forwarding owns the exit, or
+    `undefined`. A host that runs one command after another checks it to stop.
+  - `forwardedExitCode()`: `128 + signal number` for `forwardedSignal()`, or
+    `undefined`. A host that sets its own exit code keeps this one over it.
+  - `liveProcessGroups()`: the pids of the groups currently registered. A group
+    stays registered until it is empty, also after its run settles or its
+    leader exits, so a forwarded signal still kills a background member or one
+    waiting for the `SIGKILL` follow-up. The host's normal exit kills only the
+    groups whose run is still in flight, so a daemon a settled run left behind
+    keeps running.
+  - `unref` on the managed-process runner's options: the parent can exit while
+    the (usually `processGroup`) child keeps running. Such a group is not
+    tracked by `installGroupSignalForwarding`: a signal to the parent does not
+    reach it and the parent's exit does not `SIGKILL` it.
 
 ## [0.3.0] - 2026-10-15
 
@@ -324,5 +319,4 @@ entry.
   exports. A breaking change to a stable export will be listed under
   "Breaking".
 
-[0.4.0]: https://github.com/osdlc/osdlc/tree/command-seam/v0.4.0/packages/ts/command-seam
 [0.3.0]: https://github.com/sksizer/sdlc/tree/command-seam/v0.3.0/packages/command-seam

package/CONTRIBUTING.md

@@ -30,8 +30,9 @@ pnpm test
 ```
 
 Build before testing: the examples import the package by name, and under Node
-that name resolves to `dist/`. After a build, `pnpm run smoke` runs a short
-check of the built package under Node.
+that name resolves to `dist/`. After a build, `pnpm run smoke` runs
+`tests/smoke.mjs`, a short check of the built package under Node. It is not
+published.
 
 Other checks:
 
@@ -55,4 +56,7 @@ is installed.
   code a user would write. The change is judged by how that code reads. See
   [D-15](https://github.com/osdlc/osdlc/blob/main/packages/ts/command-seam/docs/planning/decisions/D-15-api-changes-start-from-consumer-code.md).
 - Keep comments short. Say why, not what.
-- Update `CHANGELOG.md` for changes users can see.
+- For a change users can see, add a changeset: run `pnpm changeset` at the
+  repository root. Start a breaking change's summary with `**Breaking:**`.
+  Do not edit `CHANGELOG.md` or `version` by hand; the release writes them.
+  See [packages/README.md](https://github.com/osdlc/osdlc/blob/main/packages/README.md).

package/README.md

@@ -645,8 +645,8 @@ The package is at 0.x. Each export is stable or experimental.
 - **Stable** exports are the runner contract: the runners, their options and
   results, `CommandFailed`, and the helpers around them. The runners and
   helpers are in use by other packages; a type that names their options or
-  results is stable with them. A breaking change to one is listed under
-  "Breaking" in the CHANGELOG.
+  results is stable with them. A breaking change to one is marked
+  **Breaking** in the CHANGELOG.
 - **Experimental** exports are newer or have no user yet. Any release may
   change or remove one. Each has an `@experimental` tag in its TSDoc.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osdlc/command-seam",
-  "version": "0.0.1-stage",
+  "version": "0.4.1",
   "description": "Injectable subprocess runner for Node: capture, stream and managed-process runners, hard timeouts, failures as results.",
   "license": "MIT",
   "author": "SK Sizer",
@@ -49,7 +49,6 @@
   },
   "files": [
     "dist/",
-    "smoke.mjs",
     "index.ts",
     "sync.ts",
     "async.ts",
@@ -88,7 +87,7 @@
     "build": "tsc -p tsconfig.build.json",
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "test": "bun test",
-    "smoke": "node smoke.mjs",
+    "smoke": "node tests/smoke.mjs",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "oxlint .",

package/smoke.mjs

@@ -1,61 +0,0 @@
-// Runs the BUILT package under Node, which no other check does: `bun test`
-// resolves the `bun` export condition to the TypeScript sources, so dist/ is
-// compiled and never executed. A broken emit — an unrewritten `.ts` import, a
-// dependency with no dist/ of its own — passes every other gate and fails on
-// the consumer's machine.
-//
-// Deliberately not a test-runner suite: it must run from the extracted
-// snapshot with only `dist/` and production dependencies present.
-
-import { strict as assert } from 'node:assert'
-import { spawnRunner, runChecked, CommandFailed, asAsync, withDefaults } from './dist/index.js'
-import { fakeProcess, fakeRunner } from './dist/testing.js'
-
-const runner = spawnRunner('node')
-const ok = runner.run(['-e', "process.stdout.write('hi')"], { cwd: process.cwd() })
-assert.equal(ok.exitCode, 0)
-assert.equal(ok.stdout, 'hi')
-
-const bad = runner.run(['-e', "process.stderr.write('boom'); process.exit(3)"], {
-  cwd: process.cwd(),
-})
-assert.equal(bad.exitCode, 3)
-assert.match(bad.stderr, /boom/)
-
-// `run` never throws; `runChecked` does.
-assert.throws(
-  () => runChecked(runner, ['-e', 'process.exit(1)'], { cwd: process.cwd() }),
-  (e) => e instanceof CommandFailed && e.argv.length === 2,
-)
-
-// detail joins both streams, empty ones dropped — the reason it exists is a
-// command that explains itself on stdout while git reports failure on stderr.
-const both = new CommandFailed(['x'], { exitCode: 1, stdout: 'why\n', stderr: 'what\n' })
-assert.equal(both.detail, 'what\nwhy')
-assert.equal(new CommandFailed(['x'], { exitCode: 1, stdout: 'only\n', stderr: '' }).detail, 'only')
-
-// env merges over the parent environment.
-const withEnv = runner.run(['-e', "process.stdout.write(process.env.SMOKE_VAR ?? '')"], {
-  cwd: process.cwd(),
-  env: { SMOKE_VAR: 'set' },
-})
-assert.equal(withEnv.stdout, 'set')
-
-const async = asAsync(runner)
-const viaAsync = await async.run(['-e', "process.stdout.write('async')"], { cwd: process.cwd() })
-assert.equal(viaAsync.stdout, 'async')
-
-// An invalid timeoutMs is a caller error.
-assert.throws(() => runner.run(['-e', ''], { cwd: process.cwd(), timeoutMs: 0 }), RangeError)
-
-const bound = withDefaults(runner, { cwd: process.cwd() })
-assert.equal(bound.run(['-e', "process.stdout.write('bound')"]).stdout, 'bound')
-
-// The /testing entry point, built.
-const fake = fakeRunner({ 'rev-parse HEAD': { stdout: 'abc\n' } })
-assert.equal(runChecked(fake.runner, ['rev-parse', 'HEAD'], { cwd: '/' }).stdout, 'abc\n')
-const proc = fakeProcess()
-proc.kill()
-assert.equal((await proc.exited).reason, 'abort')
-
-console.log('command-seam smoke: OK')