siginfo 2.0.0

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/siginfo@2.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/siginfo@2.0.0
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:a3d79f601e100dd71fdd0ea301b3e48a2bae22e8974569d678d713e5ae7c0190","constraints":{"executionContext":"node"},"contract":["siginfo is a function that registers listener callbacks for process signal handling","siginfo attaches SIGINFO and SIGUSR1 listeners when force flag is set to true","siginfo does not attach listeners in non-TTY environments when force flag is not true","invoking process signal events executes the registered query callback","siginfo returns an unsubscribe function that removes SIGINFO and SIGUSR1 listeners","calling unsubscribe multiple times is safe and maintains detached listener state"],"goal":"verify pkg:npm/siginfo@2.0.0","kind":"HOW","packages":["pkg:npm/siginfo@2.0.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/siginfo@2.0.0"],"schemaVersion":1,"subject":"pkg:npm/siginfo@2.0.0","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-siginfo",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-siginfo",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "siginfo": "2.0.0"
      }
    },
    "node_modules/siginfo": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
      "license": "ISC"
    }
  }
}

{
  "name": "sample-siginfo",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for siginfo@2.0.0",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "siginfo": "2.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/siginfo@2.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/siginfo@2.0.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const siginfo = require('siginfo');

/**
 * Attaches a query function to SIGINFO and SIGUSR1 process signals.
 *
 * @param {Function} queryFn - Callback invoked when a signal is received.
 * @param {boolean} [force=false] - Whether to attach listeners even in non-TTY environments.
 * @returns {Function} Unsubscribe function to remove the attached signal listeners.
 */
function attachSiginfo(queryFn, force) {
  return siginfo(queryFn, force);
}

module.exports = {
  siginfo,
  attachSiginfo
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const { siginfo, attachSiginfo } = require('../src/index.js');

async function testAll() {
  // 1. siginfo is a function that registers listener callbacks for process signal handling
  assert.equal(typeof siginfo, 'function', 'siginfo must export a function');
  assert.equal(typeof attachSiginfo, 'function', 'attachSiginfo helper must be a function');

  // 2. siginfo attaches SIGINFO and SIGUSR1 listeners when force flag is set to true
  const initialSigusr1Listeners = process.listeners('SIGUSR1').length;
  const initialSiginfoListeners = process.listeners('SIGINFO').length;

  let triggeredCount = 0;
  const unsubscribe = siginfo(() => {
    triggeredCount += 1;
  }, true);

  assert.equal(
    process.listeners('SIGUSR1').length,
    initialSigusr1Listeners + 1,
    'SIGUSR1 listener count should increase when force=true'
  );
  assert.equal(
    process.listeners('SIGINFO').length,
    initialSiginfoListeners + 1,
    'SIGINFO listener count should increase when force=true'
  );

  // 3. siginfo does not attach listeners in non-TTY environments when force flag is not true
  const beforeNonTtyUsr1 = process.listeners('SIGUSR1').length;
  const wasTty = process.stderr.isTTY;
  process.stderr.isTTY = false;
  try {
    let dummyCalls = 0;
    const unsubNonTty = siginfo(() => {
      dummyCalls += 1;
    }, false);
    assert.equal(
      process.listeners('SIGUSR1').length,
      beforeNonTtyUsr1,
      'SIGUSR1 listener should not attach in non-TTY when force=false'
    );
    unsubNonTty();
  } finally {
    process.stderr.isTTY = wasTty;
  }

  // 4. invoking process signal events executes the registered query callback
  assert.equal(triggeredCount, 0, 'Callback should not be triggered before signal emission');
  process.emit('SIGUSR1');
  assert.equal(triggeredCount, 1, 'SIGUSR1 emission should trigger the callback');
  process.emit('SIGINFO');
  assert.equal(triggeredCount, 2, 'SIGINFO emission should trigger the callback');

  // 5. siginfo returns an unsubscribe function that removes SIGINFO and SIGUSR1 listeners
  assert.equal(typeof unsubscribe, 'function', 'siginfo must return an unsubscribe function');
  unsubscribe();

  assert.equal(
    process.listeners('SIGUSR1').length,
    initialSigusr1Listeners,
    'SIGUSR1 listener count should return to initial after unsubscribe'
  );
  assert.equal(
    process.listeners('SIGINFO').length,
    initialSiginfoListeners,
    'SIGINFO listener count should return to initial after unsubscribe'
  );

  process.emit('SIGUSR1');
  assert.equal(triggeredCount, 2, 'Signal emission after unsubscribe must not trigger callback');

  // 6. calling unsubscribe multiple times is safe and maintains detached listener state
  unsubscribe();
  assert.equal(
    process.listeners('SIGUSR1').length,
    initialSigusr1Listeners,
    'SIGUSR1 listener count should remain initial after redundant unsubscribe'
  );

  console.log('All siginfo contract tests passed successfully.');
}

testAll().catch((err) => {
  console.error('Contract test failure:', err);
  process.exit(1);
});