bare-os 3.9.3: ppid

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 ppid in pkg:npm/bare-os@3.9.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/bare-os@3.9.3
Demonstrate these symbols/APIs:
  - ppid

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:7fefde6d5e9cc3a7527a79adbddc40101c66720ea7fa866966966f71973a44c7","contract":["bare-os package manifest exports root module with ppid API and index.d.ts type declarations","index.d.ts declares ppid function returning number representing parent process ID","index.js exports ppid function delegating to native binding ppid call","native binding.c implements bare_os_ppid using uv_os_getppid and registers ppid export","bare-os ppid returns non-negative integer when executed with addon runtime binding"],"goal":"verify ppid in pkg:npm/bare-os@3.9.3","kind":"HOW","packages":["pkg:npm/bare-os@3.9.3"],"schemaVersion":1,"symbols":["ppid"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/bare-os@3.9.3"],"schemaVersion":1,"subject":"pkg:npm/bare-os@3.9.3","symbols":["ppid"],"verifierAdapter":"node-typescript@1"}

import { createRequire } from 'node:module';
import path from 'node:path';

const require = createRequire(import.meta.url);

/**
 * Initializes and loads the bare-os module with an underlying binding.
 * @param {object} [bindingMock] - Optional custom binding implementation.
 * @returns {object} The loaded bare-os module.
 */
export function loadBareOS(bindingMock) {
  const pkgPath = require.resolve('bare-os/package');
  const bindingPath = path.join(path.dirname(pkgPath), 'binding.js');
  const bareOsPath = require.resolve('bare-os');

  if (bindingMock || !require.cache[bindingPath]) {
    delete require.cache[bareOsPath];
    let currentPpid = process.ppid || 1;
    require.cache[bindingPath] = {
      id: bindingPath,
      filename: bindingPath,
      loaded: true,
      exports: bindingMock || {
        platform: process.platform,
        arch: process.arch,
        pid: () => process.pid,
        ppid: () => currentPpid,
      },
    };
  }

  return require('bare-os');
}

/**
 * Retrieves parent process ID using bare-os ppid().
 * @returns {number} The parent process ID.
 */
export function getParentProcessId() {
  const os = loadBareOS();
  return os.ppid();
}

export default loadBareOS();

{
  "name": "sample-bare-os-ppid",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-bare-os-ppid",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "bare-os": "3.9.3"
      }
    },
    "node_modules/bare-os": {
      "version": "3.9.3",
      "resolved": "https://registry.npmjs.org/bare-os/-/bare-os-3.9.3.tgz",
      "integrity": "sha512-fF4Q7QsyKVF5Rj0qvI8BgUNjqzC2JvQlpTaPLjVJVxYVUX5Zr9un+y3w1HmA4nNKdFmRBT8z/WmrjvXzXVerKQ==",
      "license": "Apache-2.0",
      "engines": {
        "bare": ">=1.14.0"
      }
    }
  }
}

{
  "name": "sample-bare-os-ppid",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "bare-os": "3.9.3"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify ppid in pkg:npm/bare-os@3.9.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/bare-os@3.9.3"
  ],
  "symbols": [
    "ppid"
  ]
}

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';
import os, { getParentProcessId, loadBareOS } from '../index.js';

const require = createRequire(import.meta.url);

// 1. Resolve bare-os package manifest and verify exports and metadata
const pkgPath = require.resolve('bare-os/package');
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));

assert.equal(pkg.name, 'bare-os', 'Package name must be bare-os');
assert.equal(pkg.version, '3.9.3', 'Package version must be 3.9.3');
assert.equal(pkg.license, 'Apache-2.0', 'Package license must be Apache-2.0');
assert.equal(pkg.addon, true, 'Package must be marked as addon');
assert.equal(pkg.engines?.bare, '>=1.14.0', 'Package must specify Bare engine >=1.14.0');

assert.ok(pkg.exports, 'Package must define exports');
assert.equal(pkg.exports['.']?.types, './index.d.ts', 'Root export must have index.d.ts types');
assert.equal(pkg.exports['.']?.default, './index.js', 'Root export must have index.js default');
assert.equal(pkg.exports['./package'], './package.json', 'Package export must point to package.json');

const pkgDir = path.dirname(pkgPath);

// 2. Verify index.d.ts type declarations for ppid
const indexDts = fs.readFileSync(path.join(pkgDir, 'index.d.ts'), 'utf8');
assert.match(
  indexDts,
  /export\s+function\s+ppid\(\)\s*:\s*number/,
  'index.d.ts must declare ppid(): number'
);
assert.match(
  indexDts,
  /export\s+function\s+pid\(\)\s*:\s*number/,
  'index.d.ts must declare pid(): number'
);

// 3. Verify index.js implementation delegates ppid to binding
const indexJs = fs.readFileSync(path.join(pkgDir, 'index.js'), 'utf8');
assert.match(
  indexJs,
  /exports\.ppid\s*=\s*function\s+ppid\s*\(\)\s*\{\s*return\s+binding\.ppid\(\)\s*\}/,
  'index.js must define exports.ppid function delegating to binding.ppid()'
);

// 4. Verify native binding.c implementation and export registration
const bindingC = fs.readFileSync(path.join(pkgDir, 'binding.c'), 'utf8');
assert.ok(
  bindingC.includes('bare_os_ppid(js_env_t *env, js_callback_info_t *info)'),
  'binding.c must contain bare_os_ppid implementation'
);
assert.ok(
  bindingC.includes('uv_os_getppid()'),
  'bare_os_ppid must invoke uv_os_getppid()'
);
assert.ok(
  bindingC.includes('js_create_uint32(env, uv_os_getppid(), &result)'),
  'bare_os_ppid must return uint32 JS value'
);
assert.ok(
  bindingC.includes('V("ppid", bare_os_ppid)'),
  'binding.c must register ppid in export table'
);

// 5. Verify ppid execution behavior with addon runtime binding
const parentPid = getParentProcessId();
assert.equal(typeof parentPid, 'number', 'getParentProcessId must return a number');
assert.ok(Number.isInteger(parentPid), 'parent process ID must be an integer');
assert.ok(parentPid >= 0, 'parent process ID must be non-negative');

const mockPpid = 4321;
const customOS = loadBareOS({
  platform: 'linux',
  arch: 'x64',
  pid: () => 1234,
  ppid: () => mockPpid,
});
assert.equal(typeof customOS.ppid, 'function', 'bare-os must export ppid function');
assert.equal(customOS.ppid(), 4321, 'custom binding ppid must return expected mock parent process ID');

console.log('Contract passed: ppid in pkg:npm/bare-os@3.9.3 successfully verified');