bare-os 3.9.3: execPath

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.execPath 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.execPath

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:4eb20d3f8ce7fdf2f02b32b142250850af4406940a2ec7620c5250eeae5491fc","contract":["bare-os package manifest exports root module with execPath API and index.d.ts type declarations","index.d.ts declares execPath function returning string representing executable path","index.js exports execPath function delegating to native binding execPath call","native binding.c implements bare_os_exec_path using uv_exepath and registers execPath export","bare-os execPath returns non-empty absolute path string when executed with addon runtime binding","getExecutablePath and isValidExecPath helpers accurately retrieve and validate executable path","execPath executes deterministically and stably across multiple invocations"],"goal":"verify bare-os.execPath in pkg:npm/bare-os@3.9.3","kind":"HOW","packages":["pkg:npm/bare-os@3.9.3"],"schemaVersion":1,"symbols":["bare-os.execPath"]},"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.execPath"],"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);

/**
 * Ensures native binding is provided when running outside Bare runtime
 * (e.g. standard Node.js where require.addon is unavailable).
 * @param {object} [customBinding] - Optional binding override.
 * @returns {object} The bare-os module instance.
 */
export function loadBareOS(customBinding) {
  const mainPath = require.resolve('bare-os');
  const bindingPath = path.join(path.dirname(mainPath), 'binding.js');

  if (customBinding || !require.cache[bindingPath]) {
    delete require.cache[mainPath];
    const defaultBinding = {
      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() { return []; },
      kill(pid, sig) { process.kill(pid, sig); },
      isLittleEndian: nodeOS.endianness() === 'LE',
      availableParallelism() { return nodeOS.availableParallelism ? nodeOS.availableParallelism() : 1; },
      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 nodeOS.freemem ? nodeOS.freemem() : 0; },
      constrainedMemory() { return 0; },
      uptime() { return nodeOS.uptime(); },
      loadavg() { return 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]; }
    };

    require.cache[bindingPath] = {
      id: bindingPath,
      filename: bindingPath,
      loaded: true,
      exports: customBinding || defaultBinding
    };
  }

  return require('bare-os');
}

const os = loadBareOS();

/**
 * Retrieves the absolute path to the current process executable.
 * @returns {string} Path of the current executable.
 */
export function getExecutablePath() {
  return os.execPath();
}

/**
 * Validates that an executable path is non-empty and absolute.
 * @param {string} [targetPath] - Optional path to validate; defaults to current execPath.
 * @returns {boolean} True if the path is a valid absolute path.
 */
export function isValidExecPath(targetPath) {
  const p = targetPath !== undefined ? targetPath : os.execPath();
  return typeof p === 'string' && p.length > 0 && path.isAbsolute(p);
}

export default os;

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

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

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';
import os, { getExecutablePath, isValidExecPath, 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');

const pkgDir = path.dirname(pkgPath);

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

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

// 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_exec_path(js_env_t *env, js_callback_info_t *info)'),
  'binding.c must contain bare_os_exec_path implementation'
);
assert.ok(
  bindingC.includes('uv_exepath(exec_path, &len)'),
  'bare_os_exec_path must invoke uv_exepath()'
);
assert.ok(
  bindingC.includes('V("execPath", bare_os_exec_path)'),
  'binding.c must register execPath in export table'
);

// 5. Verify execPath execution returning non-empty absolute path
assert.equal(typeof os.execPath, 'function', 'os.execPath must be a function');
const currentExecPath = os.execPath();
assert.equal(typeof currentExecPath, 'string', 'execPath() must return a string');
assert.ok(currentExecPath.length > 0, 'execPath() must return a non-empty string');
assert.ok(path.isAbsolute(currentExecPath), 'execPath() must return an absolute path');

// 6. Verify helper getExecutablePath and isValidExecPath
const helperPath = getExecutablePath();
assert.equal(helperPath, currentExecPath, 'getExecutablePath helper must match os.execPath()');
assert.strictEqual(isValidExecPath(), true, 'isValidExecPath must return true for current execPath');
assert.strictEqual(isValidExecPath('/usr/bin/bare'), true, 'isValidExecPath must return true for valid absolute path');
assert.strictEqual(isValidExecPath('relative/path'), false, 'isValidExecPath must return false for relative path');
assert.strictEqual(isValidExecPath(''), false, 'isValidExecPath must return false for empty string');

// 7. Verify deterministic execution across repeated calls
const firstCall = os.execPath();
const secondCall = os.execPath();
const thirdCall = os.execPath();
assert.strictEqual(firstCall, secondCall, 'repeated calls to execPath must return identical string');
assert.strictEqual(secondCall, thirdCall, 'repeated calls to execPath must remain stable');

// 8. Verify custom binding override
const customExecPath = '/custom/bin/bare';
const customOS = loadBareOS({
  platform: 'linux',
  arch: 'x64',
  execPath: () => customExecPath,
});
assert.equal(typeof customOS.execPath, 'function', 'custom bare-os must export execPath function');
assert.equal(customOS.execPath(), customExecPath, 'custom binding execPath must return custom path');

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