bare-os 3.9.3: loadavg

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 loadavg 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:
  - loadavg

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:79b7a93f07a09224bb0d0d22a58a0ec31f3268b5189613d3bdaba8c51aa8a8f2","contract":["loadavg is exported as a function on bare-os","loadavg returns an ArrayLike object containing exactly 3 numeric load metrics","loadavg returns non-negative finite numbers representing 1, 5, and 15 minute load averages","getStructuredLoadAverage maps the load metrics into min1, min5, and min15 properties","isLoadAverageValid confirms all 3 load average values are finite non-negative numbers","index.d.ts type declaration declares loadavg returning ArrayLike\u003cnumber\u003e"],"goal":"verify loadavg in pkg:npm/bare-os@3.9.3","kind":"HOW","packages":["pkg:npm/bare-os@3.9.3"],"schemaVersion":1,"symbols":["loadavg"]},"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":["loadavg"],"verifierAdapter":"node-typescript@1"}

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

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

// Ensure native binding is provided in Node.js environments where require.addon is absent
if (typeof Bare === 'undefined') {
  const mockBinding = {
    platform: process.platform,
    arch: process.arch,
    type() { return nodeOS.type(); },
    version() { return nodeOS.version ? nodeOS.version() : nodeOS.release(); },
    release() { return nodeOS.release(); },
    machine() { return nodeOS.machine ? nodeOS.machine() : process.arch; },
    execPath() { return process.execPath; },
    pid() { return process.pid; },
    ppid() { return process.ppid; },
    cwd() { return process.cwd(); },
    chdir(dir) { process.chdir(dir); },
    tmpdir() { return nodeOS.tmpdir(); },
    homedir() { return nodeOS.homedir(); },
    hostname() { return nodeOS.hostname(); },
    userInfo(uid) { return nodeOS.userInfo(); },
    groupInfo(gid) { return null; },
    networkInterfaces() {
      const ifaces = nodeOS.networkInterfaces();
      const result = [];
      for (const [name, addrs] of Object.entries(ifaces)) {
        if (addrs) {
          for (const addr of addrs) {
            result.push({ name, ...addr });
          }
        }
      }
      return result;
    },
    kill(pid, sig) { process.kill(pid, sig); },
    isLittleEndian: nodeOS.endianness() === 'LE',
    availableParallelism() { return nodeOS.availableParallelism ? nodeOS.availableParallelism() : nodeOS.cpus().length; },
    cpuUsage() { return process.cpuUsage(); },
    threadCpuUsage() { return process.cpuUsage(); },
    resourceUsage() { return process.resourceUsage ? process.resourceUsage() : {}; },
    memoryUsage() { return process.memoryUsage(); },
    freemem() { return nodeOS.freemem(); },
    totalmem() { return nodeOS.totalmem(); },
    availableMemory() { return typeof nodeOS.freemem === 'function' ? nodeOS.freemem() : 0; },
    constrainedMemory() { return 0; },
    uptime() { return nodeOS.uptime(); },
    loadavg() { return new Float64Array(nodeOS.loadavg()); },
    cpus() { return nodeOS.cpus(); },
    getProcessTitle() { return process.title; },
    setProcessTitle(t) { process.title = t; },
    getPriority(pid) { return nodeOS.getPriority ? nodeOS.getPriority(pid) : 0; },
    setPriority(pid, p) { if (nodeOS.setPriority) nodeOS.setPriority(pid, p); },
    getEnvKeys() { return Object.keys(process.env); },
    getEnv(n) { return process.env[n]; },
    hasEnv(n) { return Object.prototype.hasOwnProperty.call(process.env, n); },
    setEnv(n, v) { process.env[n] = v; },
    unsetEnv(n) { delete process.env[n]; }
  };

  const mainPath = require.resolve('bare-os');
  const bindingPath = path.join(path.dirname(mainPath), 'binding.js');
  require.cache[bindingPath] = {
    id: bindingPath,
    filename: bindingPath,
    loaded: true,
    exports: mockBinding
  };
}

const os = require('bare-os');

/**
 * Returns system load average as a 3-element array-like collection.
 * @returns {ArrayLike<number>}
 */
export function getLoadAverage() {
  return os.loadavg();
}

/**
 * Returns structured load averages for 1, 5, and 15 minute intervals.
 * @returns {{ min1: number, min5: number, min15: number }}
 */
export function getStructuredLoadAverage() {
  const avg = os.loadavg();
  return {
    min1: avg[0],
    min5: avg[1],
    min15: avg[2]
  };
}

/**
 * Validates that the system load average returns a 3-element numeric sequence with finite non-negative numbers.
 * @returns {boolean}
 */
export function isLoadAverageValid() {
  const avg = os.loadavg();
  if (!avg || avg.length !== 3) return false;
  return typeof avg[0] === 'number' && Number.isFinite(avg[0]) && avg[0] >= 0 &&
         typeof avg[1] === 'number' && Number.isFinite(avg[1]) && avg[1] >= 0 &&
         typeof avg[2] === 'number' && Number.isFinite(avg[2]) && avg[2] >= 0;
}

export default os;

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

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

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

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

// 1. loadavg is exported as a function on bare-os
assert.strictEqual(typeof os.loadavg, 'function', 'os.loadavg must be a function');

// 2. loadavg returns an ArrayLike object containing exactly 3 numeric load metrics
const load = os.loadavg();
assert.ok(load !== null && typeof load === 'object', 'loadavg return value must be an object');
assert.strictEqual(load.length, 3, 'loadavg return value must have length 3');

// 3. loadavg returns non-negative finite numbers representing 1, 5, and 15 minute load averages
for (let i = 0; i < 3; i++) {
  const val = load[i];
  assert.strictEqual(typeof val, 'number', `loadavg[${i}] must be a number`);
  assert.strictEqual(Number.isFinite(val), true, `loadavg[${i}] must be a finite number`);
  assert.strictEqual(val >= 0, true, `loadavg[${i}] must be non-negative`);
}

// 4. getStructuredLoadAverage maps the load metrics into min1, min5, and min15 properties
const structured = getStructuredLoadAverage();
assert.strictEqual(typeof structured, 'object', 'getStructuredLoadAverage must return an object');
assert.strictEqual(structured.min1, load[0], 'min1 property must match 1-minute load average');
assert.strictEqual(structured.min5, load[1], 'min5 property must match 5-minute load average');
assert.strictEqual(structured.min15, load[2], 'min15 property must match 15-minute load average');

// 5. isLoadAverageValid confirms all 3 load average values are finite non-negative numbers
const isValid = isLoadAverageValid();
assert.strictEqual(isValid, true, 'isLoadAverageValid must return true for valid system load averages');

// 6. index.d.ts type declaration declares loadavg returning ArrayLike<number>
const pkgPath = require.resolve('bare-os/package');
const pkgDir = path.dirname(pkgPath);
const indexDts = fs.readFileSync(path.join(pkgDir, 'index.d.ts'), 'utf8');
assert.ok(
  indexDts.includes('export function loadavg(): ArrayLike<number>'),
  'index.d.ts must declare loadavg returning ArrayLike<number>'
);

console.log('Contract tests passed successfully.');