bare-os 3.9.3: userInfo

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

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:2a899565831b00d3f8c1f68ff9215df8b7ed42e398ef77875093bb5767878537","contract":["declares UserInfo interface with uid, gid, username, homedir, and shell properties in index.d.ts","declares userInfo function with optional numeric uid parameter returning UserInfo in index.d.ts","defines userInfo in index.js validating numeric uid when defined and delegating to native binding","implements bare_os_user_info in binding.c invoking uv_os_get_passwd and uv_os_get_passwd2 with cleanup via uv_os_free_passwd","registers userInfo in native addon exports table and verifies multi-platform prebuild artifacts"],"goal":"verify userInfo in pkg:npm/bare-os@3.9.3","kind":"HOW","packages":["pkg:npm/bare-os@3.9.3"],"schemaVersion":1,"symbols":["userInfo"]},"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":["userInfo"],"verifierAdapter":"node-typescript@1"}

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

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

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

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

// 1. Resolve package manifest and verify package structure
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);
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');

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

assert.match(
  indexDts,
  /export\s+interface\s+UserInfo\s*\{[\s\S]*?uid:\s*number[\s\S]*?gid:\s*number[\s\S]*?username:\s*string[\s\S]*?homedir:\s*string[\s\S]*?shell:\s*string\s*\|\s*null[\s\S]*?\}/,
  'index.d.ts must declare UserInfo interface with uid, gid, username, homedir, and shell'
);

assert.match(
  indexDts,
  /export\s+function\s+userInfo\s*\(\s*uid\?:\s*number\s*\)\s*:\s*UserInfo/,
  'index.d.ts must declare userInfo(uid?: number): UserInfo'
);

// 3. Verify userInfo implementation in index.js
assert.ok(fs.existsSync(indexJsPath), 'index.js must exist');
const indexJs = fs.readFileSync(indexJsPath, 'utf8');

assert.match(
  indexJs,
  /exports\.userInfo\s*=\s*function\s+userInfo\s*\(\s*uid\s*\)\s*\{[\s\S]*?if\s*\(\s*uid\s*!==\s*undefined\s*\)\s*validateInteger\s*\(\s*uid,\s*['"]User ID['"]\s*\)[\s\S]*?return\s+binding\.userInfo\s*\(\s*uid\s*\)[\s\S]*?\}/,
  'index.js must validate integer uid when defined and delegate to binding.userInfo(uid)'
);

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

assert.ok(
  bindingC.includes('bare_os_user_info(js_env_t *env, js_callback_info_t *info)'),
  'binding.c must implement bare_os_user_info callback function'
);
assert.ok(
  bindingC.includes('uv_os_get_passwd(&pwd)'),
  'bare_os_user_info must call uv_os_get_passwd when uid is undefined'
);
assert.ok(
  bindingC.includes('uv_os_get_passwd2(&pwd, uid)'),
  'bare_os_user_info must call uv_os_get_passwd2 when uid is specified'
);
assert.ok(
  bindingC.includes('uv_os_free_passwd(&pwd)'),
  'bare_os_user_info must free allocated passwd structure with uv_os_free_passwd'
);
assert.ok(
  bindingC.includes('js_set_named_property(env, result, "uid", uid)'),
  'bare_os_user_info must set uid property'
);
assert.ok(
  bindingC.includes('js_set_named_property(env, result, "gid", gid)'),
  'bare_os_user_info must set gid property'
);
assert.ok(
  bindingC.includes('js_set_named_property(env, result, "username", username)'),
  'bare_os_user_info must set username property'
);
assert.ok(
  bindingC.includes('js_set_named_property(env, result, "homedir", homedir)'),
  'bare_os_user_info must set homedir property'
);
assert.ok(
  bindingC.includes('js_set_named_property(env, result, "shell", shell)'),
  'bare_os_user_info must set shell property'
);
assert.ok(
  bindingC.includes('V("userInfo", bare_os_user_info)'),
  'binding.c must register userInfo in exports table'
);

// 5. Verify UserInfo structure semantics against system user data
const currentOsUser = os.userInfo();
assert.equal(typeof currentOsUser.username, 'string', 'username must be a string');
assert.equal(typeof currentOsUser.homedir, 'string', 'homedir must be a string');
assert.equal(typeof currentOsUser.uid, 'number', 'uid must be a number');
assert.equal(typeof currentOsUser.gid, 'number', 'gid must be a number');

// 6. Verify prebuild artifacts and CMake build file
assert.ok(fs.existsSync(path.join(pkgDir, 'CMakeLists.txt')), 'CMakeLists.txt must exist');
assert.ok(fs.existsSync(bindingJsPath), 'binding.js must exist');

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: userInfo in pkg:npm/bare-os@3.9.3 successfully verified');