bare-os 3.9.3: bare-os

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 bare-os 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:
  - bare-os

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:b9e8f012a8eb1c9920854724087a4b4044a707d843a4a2bd721bf164c0e8782a","contract":["validates bare-os package manifest exports mapping for root index, package json, constants, and errors modules","verifies bare-os TypeScript declarations in index.d.ts for system inspection, process control, and environment APIs","verifies JavaScript exports and validation routines in index.js for platform utilities and environment variable management","proves OSError class inheritance, error code formatting, and factory constructors in lib/errors.js","verifies constants module exports mapping signals, errnos, and process priority definitions in lib/constants.js","verifies native C binding exports registration table and libuv wrappers in binding.c","confirms native addon prebuilt binaries are packaged and non-empty for multi-platform target matrix"],"goal":"verify bare-os in pkg:npm/bare-os@3.9.3","kind":"HOW","packages":["pkg:npm/bare-os@3.9.3"],"schemaVersion":1,"symbols":["bare-os"]},"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":["bare-os"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-bare-os",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-bare-os",
      "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",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "bare-os": "3.9.3"
  }
}

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

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

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');
assert.equal(pkg.exports['./constants'].types, './lib/constants.d.ts', 'Constants export must have types');
assert.equal(pkg.exports['./constants'].default, './lib/constants.js', 'Constants export must have default js');
assert.equal(pkg.exports['./errors'].types, './lib/errors.d.ts', 'Errors export must have types');
assert.equal(pkg.exports['./errors'].default, './lib/errors.js', 'Errors export must have default js');

const pkgDir = path.dirname(pkgPath);
const indexDtsPath = path.join(pkgDir, 'index.d.ts');
const indexJsPath = path.join(pkgDir, 'index.js');
const bindingCPath = path.join(pkgDir, 'binding.c');
const bindingJsPath = path.join(pkgDir, 'binding.js');
const errorsJsPath = path.join(pkgDir, 'lib', 'errors.js');
const errorsDtsPath = path.join(pkgDir, 'lib', 'errors.d.ts');
const constantsJsPath = path.join(pkgDir, 'lib', 'constants.js');
const constantsDtsPath = path.join(pkgDir, 'lib', 'constants.d.ts');

// 2. Verify TypeScript declarations in index.d.ts
assert.ok(fs.existsSync(indexDtsPath), 'index.d.ts must exist');
const indexDts = fs.readFileSync(indexDtsPath, 'utf8');

const expectedDtsSymbols = [
  'export { constants, errors }',
  'export const EOL:',
  'export const devNull:',
  'export function platform():',
  'export function arch():',
  'export function type():',
  'export function version():',
  'export function release():',
  'export function machine():',
  'export function execPath():',
  'export function pid():',
  'export function ppid():',
  'export function cwd():',
  'export function chdir(dir: string): void',
  'export function tmpdir():',
  'export function homedir():',
  'export function hostname():',
  'export function networkInterfaces():',
  'export function kill(pid: number, signal?: string | number): void',
  'export function userInfo(uid?: number):',
  'export function groupInfo(gid?: number):',
  'export function endianness():',
  'export function availableParallelism():',
  'export function cpuUsage(previous?: CpuUsage): CpuUsage',
  'export function threadCpuUsage(previous?: CpuUsage): CpuUsage',
  'export function resourceUsage():',
  'export function memoryUsage():',
  'export function freemem():',
  'export function totalmem():',
  'export function availableMemory():',
  'export function constrainedMemory():',
  'export function uptime():',
  'export function loadavg():',
  'export function cpus():',
  'export function getProcessTitle():',
  'export function setProcessTitle(title: unknown): void',
  'export function getPriority(pid?: number): number',
  'export function setPriority(priority: number): void',
  'export function getEnvKeys(): string[]',
  'export function getEnv(name: string): string | undefined',
  'export function hasEnv(name: string): boolean',
  'export function setEnv(name: string, value: string): void',
  'export function unsetEnv(name: string): void'
];

for (const sym of expectedDtsSymbols) {
  assert.ok(indexDts.includes(sym), `index.d.ts must declare ${sym}`);
}

// 3. Verify JavaScript module structure and exports in index.js
assert.ok(fs.existsSync(indexJsPath), 'index.js must exist');
const indexJs = fs.readFileSync(indexJsPath, 'utf8');

assert.ok(indexJs.includes("exports.constants = constants"), 'index.js must export constants');
assert.ok(indexJs.includes("exports.errors = errors"), 'index.js must export errors');
assert.ok(indexJs.includes("exports.platform = function platform()"), 'index.js must export platform function');
assert.ok(indexJs.includes("exports.arch = function arch()"), 'index.js must export arch function');
assert.ok(indexJs.includes("exports.type = function type()"), 'index.js must export type function');
assert.ok(indexJs.includes("exports.cwd = function cwd()"), 'index.js must export cwd function');
assert.ok(indexJs.includes("exports.chdir = function chdir(dir)"), 'index.js must export chdir function');
assert.ok(indexJs.includes("exports.kill = function kill(pid, signal"), 'index.js must export kill function');
assert.ok(indexJs.includes("exports.endianness = function endianness()"), 'index.js must export endianness function');
assert.ok(indexJs.includes("exports.getEnv = function getEnv(name)"), 'index.js must export getEnv function');
assert.ok(indexJs.includes("exports.setEnv = function setEnv(name, value)"), 'index.js must export setEnv function');
assert.ok(indexJs.includes("exports.unsetEnv = function unsetEnv(name)"), 'index.js must export unsetEnv function');

// 4. Verify OSError implementation in lib/errors.js
assert.ok(fs.existsSync(errorsJsPath), 'lib/errors.js must exist');
assert.ok(fs.existsSync(errorsDtsPath), 'lib/errors.d.ts must exist');

const OSError = require(errorsJsPath);
const err = new OSError('Test error message', OSError, 'ERR_TEST');
assert.ok(err instanceof Error, 'OSError must inherit from Error');
assert.equal(err.name, 'OSError', 'OSError.name must be OSError');
assert.equal(err.code, 'ERR_TEST', 'OSError.code must match provided code');
assert.ok(err.message.includes('ERR_TEST: Test error message'), 'Message must format code and text');

const unknownSigErr = OSError.UNKNOWN_SIGNAL('SIGINVALID');
assert.equal(unknownSigErr.code, 'UNKNOWN_SIGNAL', 'UNKNOWN_SIGNAL factory must assign code');
assert.equal(unknownSigErr.name, 'OSError', 'UNKNOWN_SIGNAL must have name OSError');

const titleOverflowErr = OSError.TITLE_OVERFLOW('title is too long');
assert.equal(titleOverflowErr.code, 'TITLE_OVERFLOW', 'TITLE_OVERFLOW factory must assign code');
assert.equal(titleOverflowErr.name, 'OSError', 'TITLE_OVERFLOW must have name OSError');

// 5. Verify constants mapping in lib/constants.js
assert.ok(fs.existsSync(constantsJsPath), 'lib/constants.js must exist');
assert.ok(fs.existsSync(constantsDtsPath), 'lib/constants.d.ts must exist');

const constantsJs = fs.readFileSync(constantsJsPath, 'utf8');
assert.ok(constantsJs.includes("signals: binding.signals"), 'constants must map binding.signals');
assert.ok(constantsJs.includes("errnos: binding.errnos"), 'constants must map binding.errnos');
assert.ok(constantsJs.includes("priority: binding.priority"), 'constants must map binding.priority');

// 6. Verify native C binding implementation in binding.c
assert.ok(fs.existsSync(bindingCPath), 'binding.c must exist');
const bindingC = fs.readFileSync(bindingCPath, 'utf8');

assert.ok(bindingC.includes('BARE_MODULE(bare_os, bare_os_exports)'), 'binding.c must declare BARE_MODULE');
assert.ok(bindingC.includes('bare_os_exports(js_env_t *env, js_value_t *exports)'), 'binding.c must implement bare_os_exports');
assert.ok(bindingC.includes('uv_once(&bare_os_env_lock_guard, bare_os__on_env_lock_init)'), 'binding.c must initialize env lock');

const requiredBindings = [
  'V("type", bare_os_type)',
  'V("version", bare_os_version)',
  'V("release", bare_os_release)',
  'V("machine", bare_os_machine)',
  'V("execPath", bare_os_exec_path)',
  'V("pid", bare_os_pid)',
  'V("ppid", bare_os_ppid)',
  'V("cwd", bare_os_cwd)',
  'V("chdir", bare_os_chdir)',
  'V("tmpdir", bare_os_tmpdir)',
  'V("homedir", bare_os_homedir)',
  'V("hostname", bare_os_hostname)',
  'V("kill", bare_os_kill)',
  'V("availableParallelism", bare_os_available_parallelism)',
  'V("cpuUsage", bare_os_cpu_usage)',
  'V("threadCpuUsage", bare_os_cpu_usage_thread)',
  'V("resourceUsage", bare_os_resource_usage)',
  'V("memoryUsage", bare_os_memory_usage)',
  'V("freemem", bare_os_freemem)',
  'V("totalmem", bare_os_totalmem)',
  'V("availableMemory", bare_os_available_memory)',
  'V("constrainedMemory", bare_os_constrained_memory)',
  'V("uptime", bare_os_uptime)',
  'V("loadavg", bare_os_loadavg)',
  'V("cpus", bare_os_cpus)',
  'V("getProcessTitle", bare_os_get_process_title)',
  'V("setProcessTitle", bare_os_set_process_title)',
  'V("getPriority", bare_os_get_priority)',
  'V("setPriority", bare_os_set_priority)',
  'V("getEnvKeys", bare_os_get_env_keys)',
  'V("getEnv", bare_os_get_env)',
  'V("hasEnv", bare_os_has_env)',
  'V("setEnv", bare_os_set_env)',
  'V("unsetEnv", bare_os_unset_env)',
  'V("userInfo", bare_os_user_info)',
  'V("networkInterfaces", bare_os_network_interfaces)',
  'V("groupInfo", bare_os_group_info)'
];

for (const binding of requiredBindings) {
  assert.ok(bindingC.includes(binding), `binding.c must register ${binding}`);
}

// 7. Verify binding loader and CMakeLists.txt
assert.ok(fs.existsSync(bindingJsPath), 'binding.js must exist');
const bindingJs = fs.readFileSync(bindingJsPath, 'utf8');
assert.ok(bindingJs.includes('module.exports = require.addon()'), 'binding.js must load native addon via require.addon()');
assert.ok(fs.existsSync(path.join(pkgDir, 'CMakeLists.txt')), 'CMakeLists.txt must exist');

// 8. Verify prebuild native binaries for multi-platform matrix
const prebuildsDir = path.join(pkgDir, 'prebuilds');
const expectedTargets = [
  'linux-x64',
  'linux-arm64',
  'darwin-x64',
  'darwin-arm64',
  'win32-x64',
  'win32-arm64',
  'android-arm64',
  'ios-arm64'
];

for (const target of expectedTargets) {
  const prebuildPath = path.join(prebuildsDir, target, 'bare-os.bare');
  assert.ok(fs.existsSync(prebuildPath), `Prebuild binary for ${target} must exist at ${prebuildPath}`);
  const stats = fs.statSync(prebuildPath);
  assert.ok(stats.size > 0, `Prebuild binary for ${target} must not be empty`);
}

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