bare-os 3.9.3: getEnvKeys

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

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:d9c724e7f14e8a223cef410a4939812d359904c6cf8d0a62945916489f3a4b75","contract":["package manifest specifies bare-os 3.9.3 with Bare addon configuration and exports root entrypoint index.js with index.d.ts type declarations","index.d.ts declares getEnvKeys returning string array and companion getEnv, hasEnv, setEnv, and unsetEnv functions","binding.c implements bare_os_get_env_keys calling uv_os_environ and returning UTF-8 string array of environment variable keys","index.js exports getEnvKeys delegating to binding.getEnvKeys and enforces string validation on environment helper arguments","getEnvKeys returns array of environment variable keys and reflects setEnv and unsetEnv lifecycle operations"],"goal":"verify getEnvKeys in pkg:npm/bare-os@3.9.3","kind":"HOW","packages":["pkg:npm/bare-os@3.9.3"],"schemaVersion":1,"symbols":["getEnvKeys"]},"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":["getEnvKeys"],"verifierAdapter":"node-typescript@1"}

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

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

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. Package manifest verification for bare-os@3.9.3
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 Bare addon');
assert.equal(pkg.engines?.bare, '>=1.14.0', 'Package must specify Bare engine requirement');

assert.ok(pkg.exports, 'Package must define exports map');
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');

const pkgDir = path.dirname(pkgPath);

// 2. TypeScript declaration inspection for getEnvKeys and environment APIs
const indexDts = fs.readFileSync(path.join(pkgDir, 'index.d.ts'), 'utf8');

assert.ok(indexDts.includes('export function getEnvKeys(): string[]'), 'index.d.ts must declare getEnvKeys(): string[]');
assert.ok(indexDts.includes('export function getEnv(name: string): string | undefined'), 'index.d.ts must declare getEnv');
assert.ok(indexDts.includes('export function hasEnv(name: string): boolean'), 'index.d.ts must declare hasEnv');
assert.ok(indexDts.includes('export function setEnv(name: string, value: string): void'), 'index.d.ts must declare setEnv');
assert.ok(indexDts.includes('export function unsetEnv(name: string): void'), 'index.d.ts must declare unsetEnv');

// 3. Native C binding inspection
const bindingCPath = path.join(pkgDir, 'binding.c');
assert.ok(fs.existsSync(bindingCPath), 'binding.c must exist in package root');
const bindingC = fs.readFileSync(bindingCPath, 'utf8');

assert.ok(bindingC.includes('bare_os_get_env_keys'), 'binding.c must define bare_os_get_env_keys');
assert.ok(bindingC.includes('uv_os_environ'), 'binding.c must call uv_os_environ for retrieving environment keys');
assert.ok(bindingC.includes('uv_os_free_environ'), 'binding.c must call uv_os_free_environ to release environment buffer');
assert.ok(bindingC.includes('js_create_array_with_length'), 'binding.c must construct array for environment keys');
assert.ok(bindingC.includes('V("getEnvKeys", bare_os_get_env_keys)'), 'binding.c must register getEnvKeys export');

// 4. Module source inspection (index.js)
const indexJs = fs.readFileSync(path.join(pkgDir, 'index.js'), 'utf8');
assert.ok(indexJs.includes('exports.getEnvKeys = function getEnvKeys()'), 'index.js must export getEnvKeys');
assert.ok(indexJs.includes('return binding.getEnvKeys()'), 'index.js getEnvKeys must delegate to binding');
assert.ok(indexJs.includes("validateString(name, 'Name')"), 'index.js must validate name argument as string');
assert.ok(indexJs.includes("validateString(value, 'Value')"), 'index.js must validate value argument as string');

// 5. Runtime binding execution and environment key lifecycle
const bindingPath = path.join(pkgDir, 'binding.js');
const envStore = new Map([
  ['NODE_ENV', 'test'],
  ['SAMPLE_ENV_A', 'sample_val_a'],
  ['SAMPLE_ENV_B', 'sample_val_b']
]);

require.cache[bindingPath] = {
  id: bindingPath,
  filename: bindingPath,
  loaded: true,
  exports: {
    getEnvKeys: () => Array.from(envStore.keys()),
    getEnv: (name) => envStore.get(name),
    hasEnv: (name) => envStore.has(name),
    setEnv: (name, value) => { envStore.set(name, value); },
    unsetEnv: (name) => { envStore.delete(name); }
  }
};

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

assert.equal(typeof bareOs.getEnvKeys, 'function', 'bare-os must export getEnvKeys function');

// Verify initial keys
const initialKeys = bareOs.getEnvKeys();
assert.ok(Array.isArray(initialKeys), 'getEnvKeys() must return an Array');
assert.equal(initialKeys.length, 3, 'initial keys length must match store');
assert.ok(initialKeys.includes('NODE_ENV'), 'getEnvKeys must include NODE_ENV');
assert.ok(initialKeys.includes('SAMPLE_ENV_A'), 'getEnvKeys must include SAMPLE_ENV_A');
assert.ok(initialKeys.includes('SAMPLE_ENV_B'), 'getEnvKeys must include SAMPLE_ENV_B');

// Verify setEnv lifecycle updates getEnvKeys
const testKey = 'CSX_SAMPLE_KEY';
const testValue = 'csx_sample_value_123';
assert.equal(bareOs.hasEnv(testKey), false, 'hasEnv must be false before setEnv');
assert.equal(bareOs.getEnv(testKey), undefined, 'getEnv must return undefined before setEnv');
assert.ok(!bareOs.getEnvKeys().includes(testKey), 'getEnvKeys must not contain key before setEnv');

bareOs.setEnv(testKey, testValue);
assert.equal(bareOs.hasEnv(testKey), true, 'hasEnv must be true after setEnv');
assert.equal(bareOs.getEnv(testKey), testValue, 'getEnv must return stored value after setEnv');
const keysAfterSet = bareOs.getEnvKeys();
assert.ok(keysAfterSet.includes(testKey), 'getEnvKeys must contain key after setEnv');
assert.equal(keysAfterSet.length, 4, 'keys count must increase by 1');

// Verify unsetEnv lifecycle updates getEnvKeys
bareOs.unsetEnv(testKey);
assert.equal(bareOs.hasEnv(testKey), false, 'hasEnv must be false after unsetEnv');
assert.equal(bareOs.getEnv(testKey), undefined, 'getEnv must return undefined after unsetEnv');
const keysAfterUnset = bareOs.getEnvKeys();
assert.ok(!keysAfterUnset.includes(testKey), 'getEnvKeys must not contain key after unsetEnv');
assert.equal(keysAfterUnset.length, 3, 'keys count must return to original');

// Verify argument validation in helper functions
assert.throws(() => bareOs.getEnv(123), TypeError, 'getEnv with non-string must throw TypeError');
assert.throws(() => bareOs.hasEnv(null), TypeError, 'hasEnv with non-string must throw TypeError');
assert.throws(() => bareOs.setEnv('KEY', 456), TypeError, 'setEnv with non-string value must throw TypeError');
assert.throws(() => bareOs.setEnv(false, 'VAL'), TypeError, 'setEnv with non-string key must throw TypeError');
assert.throws(() => bareOs.unsetEnv({}), TypeError, 'unsetEnv with non-string key must throw TypeError');

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