bare-posix 1.0.1

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 pkg:npm/bare-posix@1.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/bare-posix@1.0.1

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:20846d0208e8f5c38076070c2ae77308bd35e17a1a6651bd76934d51216687a5","contract":["package manifest specifies Bare native addon configuration, Apache-2.0 license, and exports for root and package subpaths","declares POSIX user and group ID management and lookup functions in TypeScript definition index.d.ts","implements binding loader via require.addon and wrapper functions with string name resolution in index.js","provides non-POSIX fallback implementations for android and win32 returning error or sentinel values in unsupported.js","implements native Bare module binding bare_posix calling POSIX system APIs in binding.c with CMakeLists.txt build definition","provides multi-platform precompiled .bare addon binaries including linux-x64, linux-arm64, darwin, and ios targets"],"goal":"verify pkg:npm/bare-posix@1.0.1","kind":"HOW","packages":["pkg:npm/bare-posix@1.0.1"],"schemaVersion":1},"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-posix@1.0.1"],"schemaVersion":1,"subject":"pkg:npm/bare-posix@1.0.1","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-bare-posix",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-bare-posix",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "bare-posix": "1.0.1"
      }
    },
    "node_modules/bare-posix": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/bare-posix/-/bare-posix-1.0.1.tgz",
      "integrity": "sha512-b4quA8dyRVvX0aFIAIiev5zFATHwIUGr42Gmt+CqiBNg/bdsNkrj4bbkeotMOMiljJS4DCME5kywJO/TFwKo1A==",
      "license": "Apache-2.0"
    }
  }
}

{
  "name": "sample-bare-posix",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "bare-posix": "1.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/bare-posix@1.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/bare-posix@1.0.1"
  ]
}

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-posix package manifest and verify exports and metadata
const pkgPath = require.resolve('bare-posix/package');
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));

assert.equal(pkg.name, 'bare-posix', 'Package name must be bare-posix');
assert.equal(pkg.version, '1.0.1', 'Package version must be 1.0.1');
assert.equal(pkg.license, 'Apache-2.0', 'Package license must be Apache-2.0');
assert.equal(pkg.addon, true, 'Package must be marked as Bare addon');

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

assert.deepEqual(
  pkg.files,
  ['index.js', 'index.d.ts', 'unsupported.js', 'binding.c', 'binding.js', 'CMakeLists.txt', 'prebuilds'],
  'Package files array must contain expected source and build files'
);

const pkgDir = path.dirname(pkgPath);

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

assert.ok(indexDts.includes('export function getgid(): number'), 'index.d.ts must declare getgid');
assert.ok(indexDts.includes('export function setgid(id: number | string): void'), 'index.d.ts must declare setgid');
assert.ok(indexDts.includes('export function getegid(): number'), 'index.d.ts must declare getegid');
assert.ok(indexDts.includes('export function setegid(id: number | string): void'), 'index.d.ts must declare setegid');
assert.ok(indexDts.includes('export function getuid(): number'), 'index.d.ts must declare getuid');
assert.ok(indexDts.includes('export function setuid(id: number | string): void'), 'index.d.ts must declare setuid');
assert.ok(indexDts.includes('export function geteuid(): number'), 'index.d.ts must declare geteuid');
assert.ok(indexDts.includes('export function seteuid(id: number | string): void'), 'index.d.ts must declare seteuid');
assert.ok(indexDts.includes('export function getgroups(): number[]'), 'index.d.ts must declare getgroups');
assert.ok(indexDts.includes('export function getgrnam(name: string): Group | null'), 'index.d.ts must declare getgrnam');
assert.ok(indexDts.includes('export function getpwnam(name: string): Passwd | null'), 'index.d.ts must declare getpwnam');

assert.ok(indexDts.includes('export interface Group'), 'index.d.ts must declare Group interface');
assert.ok(indexDts.includes('groupname: string'), 'Group interface must have groupname');
assert.ok(indexDts.includes('members: string[]'), 'Group interface must have members');

assert.ok(indexDts.includes('export interface Passwd'), 'index.d.ts must declare Passwd interface');
assert.ok(indexDts.includes('username: string'), 'Passwd interface must have username');
assert.ok(indexDts.includes('homedir: string'), 'Passwd interface must have homedir');
assert.ok(indexDts.includes('shell: string'), 'Passwd interface must have shell');

// 3. Verify JavaScript module wrappers (index.js, binding.js, unsupported.js)
const indexJsPath = path.join(pkgDir, 'index.js');
assert.ok(fs.existsSync(indexJsPath), 'index.js must exist');
const indexJs = fs.readFileSync(indexJsPath, 'utf8');
assert.ok(indexJs.includes("require('./binding')"), 'index.js must require binding');
assert.ok(indexJs.includes('exports.getgid = binding.getgid'), 'index.js must export getgid');
assert.ok(indexJs.includes('exports.setgid = function setgid(id)'), 'index.js must export setgid');
assert.ok(indexJs.includes('exports.getegid = binding.getegid'), 'index.js must export getegid');
assert.ok(indexJs.includes('exports.setegid = function setegid(id)'), 'index.js must export setegid');
assert.ok(indexJs.includes('exports.getuid = binding.getuid'), 'index.js must export getuid');
assert.ok(indexJs.includes('exports.setuid = function setuid(id)'), 'index.js must export setuid');
assert.ok(indexJs.includes('exports.geteuid = binding.geteuid'), 'index.js must export geteuid');
assert.ok(indexJs.includes('exports.seteuid = function seteuid(id)'), 'index.js must export seteuid');
assert.ok(indexJs.includes('exports.getgroups = binding.getgroups'), 'index.js must export getgroups');
assert.ok(indexJs.includes('exports.getgrnam = binding.getgrnam'), 'index.js must export getgrnam');
assert.ok(indexJs.includes('exports.getpwnam = binding.getpwnam'), 'index.js must export getpwnam');

const bindingJsPath = path.join(pkgDir, 'binding.js');
assert.ok(fs.existsSync(bindingJsPath), 'binding.js must exist');
const bindingJs = fs.readFileSync(bindingJsPath, 'utf8');
assert.ok(bindingJs.includes('require.addon()'), 'binding.js must invoke require.addon()');

// 4. Verify unsupported platform fallback module (unsupported.js)
const unsupportedPath = path.join(pkgDir, 'unsupported.js');
assert.ok(fs.existsSync(unsupportedPath), 'unsupported.js must exist');
const unsupported = require(unsupportedPath);

assert.equal(unsupported.getgid(), -1, 'unsupported getgid must return -1');
assert.equal(unsupported.getegid(), -1, 'unsupported getegid must return -1');
assert.equal(unsupported.getuid(), -1, 'unsupported getuid must return -1');
assert.equal(unsupported.geteuid(), -1, 'unsupported geteuid must return -1');
assert.deepEqual(unsupported.getgroups(), [], 'unsupported getgroups must return empty array');
assert.equal(unsupported.getgrnam('root'), null, 'unsupported getgrnam must return null');
assert.equal(unsupported.getpwnam('root'), null, 'unsupported getpwnam must return null');

assert.throws(() => unsupported.setgid(0), /Platform not supported/, 'unsupported setgid must throw');
assert.throws(() => unsupported.setegid(0), /Platform not supported/, 'unsupported setegid must throw');
assert.throws(() => unsupported.setuid(0), /Platform not supported/, 'unsupported setuid must throw');
assert.throws(() => unsupported.seteuid(0), /Platform not supported/, 'unsupported seteuid must throw');

// 5. Verify C native addon source and build configuration
const bindingCPath = path.join(pkgDir, 'binding.c');
assert.ok(fs.existsSync(bindingCPath), 'binding.c must exist');
const bindingC = fs.readFileSync(bindingCPath, 'utf8');
assert.ok(bindingC.includes('#include <bare.h>'), 'binding.c must include <bare.h>');
assert.ok(bindingC.includes('#include <grp.h>'), 'binding.c must include <grp.h>');
assert.ok(bindingC.includes('#include <js.h>'), 'binding.c must include <js.h>');
assert.ok(bindingC.includes('#include <pwd.h>'), 'binding.c must include <pwd.h>');
assert.ok(bindingC.includes('#include <unistd.h>'), 'binding.c must include <unistd.h>');
assert.ok(bindingC.includes('bare_posix_getgid'), 'binding.c must implement bare_posix_getgid');
assert.ok(bindingC.includes('bare_posix_setgid'), 'binding.c must implement bare_posix_setgid');
assert.ok(bindingC.includes('bare_posix_getegid'), 'binding.c must implement bare_posix_getegid');
assert.ok(bindingC.includes('bare_posix_setegid'), 'binding.c must implement bare_posix_setegid');
assert.ok(bindingC.includes('bare_posix_getuid'), 'binding.c must implement bare_posix_getuid');
assert.ok(bindingC.includes('bare_posix_setuid'), 'binding.c must implement bare_posix_setuid');
assert.ok(bindingC.includes('bare_posix_geteuid'), 'binding.c must implement bare_posix_geteuid');
assert.ok(bindingC.includes('bare_posix_seteuid'), 'binding.c must implement bare_posix_seteuid');
assert.ok(bindingC.includes('bare_posix_getgroups'), 'binding.c must implement bare_posix_getgroups');
assert.ok(bindingC.includes('bare_posix_getgrnam'), 'binding.c must implement bare_posix_getgrnam');
assert.ok(bindingC.includes('bare_posix_getpwnam'), 'binding.c must implement bare_posix_getpwnam');
assert.ok(bindingC.includes('BARE_MODULE(bare_posix, bare_posix_exports)'), 'binding.c must define BARE_MODULE');

const cmakePath = path.join(pkgDir, 'CMakeLists.txt');
assert.ok(fs.existsSync(cmakePath), 'CMakeLists.txt must exist');
const cmake = fs.readFileSync(cmakePath, 'utf8');
assert.ok(cmake.includes('project(bare_posix C)'), 'CMakeLists.txt must define project bare_posix');
assert.ok(cmake.includes('add_bare_module(bare_posix)'), 'CMakeLists.txt must declare bare module');
assert.ok(cmake.includes('binding.c'), 'CMakeLists.txt must include binding.c');

// 6. Verify prebuilt native binaries across architectures
const prebuildsDir = path.join(pkgDir, 'prebuilds');
assert.ok(fs.existsSync(prebuildsDir), 'prebuilds directory must exist');

const expectedTargets = [
  'darwin-arm64',
  'darwin-x64',
  'ios-arm64-simulator',
  'ios-arm64',
  'ios-x64-simulator',
  'linux-arm64',
  'linux-x64'
];

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

const linuxX64Binary = fs.readFileSync(path.join(prebuildsDir, 'linux-x64', 'bare-posix.bare'));
assert.ok(linuxX64Binary.length > 1000, 'linux-x64 prebuild binary size must exceed 1000 bytes');

// 7. Verify index.js wrapper logic with mocked binding
const mockCalls = [];
const mockBinding = {
  getgid: () => 1000,
  setgid: (id) => { mockCalls.push(['setgid', id]); },
  getegid: () => 1000,
  setegid: (id) => { mockCalls.push(['setegid', id]); },
  getuid: () => 1000,
  setuid: (id) => { mockCalls.push(['setuid', id]); },
  geteuid: () => 1000,
  seteuid: (id) => { mockCalls.push(['seteuid', id]); },
  getgroups: () => [1000, 4, 27],
  getgrnam: (name) => {
    if (name === 'adm') return { groupname: 'adm', passwd: 'x', gid: 4, members: ['user'] };
    return null;
  },
  getpwnam: (name) => {
    if (name === 'root') return { username: 'root', passwd: 'x', uid: 0, gid: 0, gecos: 'root', homedir: '/root', shell: '/bin/bash' };
    return null;
  }
};

require.cache[bindingJsPath] = {
  id: bindingJsPath,
  filename: bindingJsPath,
  loaded: true,
  exports: mockBinding
};

delete require.cache[indexJsPath];
const posix = require(indexJsPath);

assert.equal(posix.getgid(), 1000, 'getgid must return gid from binding');
assert.equal(posix.getegid(), 1000, 'getegid must return egid from binding');
assert.equal(posix.getuid(), 1000, 'getuid must return uid from binding');
assert.equal(posix.geteuid(), 1000, 'geteuid must return euid from binding');
assert.deepEqual(posix.getgroups(), [1000, 4, 27], 'getgroups must return groups from binding');
assert.deepEqual(posix.getgrnam('adm'), { groupname: 'adm', passwd: 'x', gid: 4, members: ['user'] }, 'getgrnam must return group object');
assert.deepEqual(posix.getpwnam('root'), { username: 'root', passwd: 'x', uid: 0, gid: 0, gecos: 'root', homedir: '/root', shell: '/bin/bash' }, 'getpwnam must return passwd object');

posix.setgid(500);
assert.deepEqual(mockCalls[mockCalls.length - 1], ['setgid', 500], 'Numeric setgid must pass integer directly');

posix.setegid(501);
assert.deepEqual(mockCalls[mockCalls.length - 1], ['setegid', 501], 'Numeric setegid must pass integer directly');

posix.setuid(502);
assert.deepEqual(mockCalls[mockCalls.length - 1], ['setuid', 502], 'Numeric setuid must pass integer directly');

posix.seteuid(503);
assert.deepEqual(mockCalls[mockCalls.length - 1], ['seteuid', 503], 'Numeric seteuid must pass integer directly');

posix.setgid('adm');
assert.deepEqual(mockCalls[mockCalls.length - 1], ['setgid', 4], 'String setgid must resolve groupname to gid');

posix.setegid('adm');
assert.deepEqual(mockCalls[mockCalls.length - 1], ['setegid', 4], 'String setegid must resolve groupname to gid');

posix.setuid('root');
assert.deepEqual(mockCalls[mockCalls.length - 1], ['setuid', 0], 'String setuid must resolve username to uid');

posix.seteuid('root');
assert.deepEqual(mockCalls[mockCalls.length - 1], ['seteuid', 0], 'String seteuid must resolve username to uid');

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