bare-env 3.0.1: env

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-env@3.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/bare-env@3.0.1
Demonstrate these symbols/APIs:
  - env

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:2290350d231beaa40fde49141ebf7ee20ae28a8ddc1ca9837fa58e9347d55796","contract":["package manifest specifies Apache-2.0 license, bare-os dependency, and exports for root and package subpaths","declares Env index signature interface and env constant in TypeScript definitions (index.d.ts)","exports a Proxy object delegating environment variable access to bare-os","supports getting, setting, and checking presence of environment variables via property access and the in operator","coerces number and boolean values to strings when setting environment variables","throws an Error when attempting to set non-primitive values such as objects, arrays, functions, or symbols","delegates ownKeys and getOwnPropertyDescriptor traps allowing Object.keys enumeration and descriptor lookup","unsets environment variables on deleteProperty while the trap returns falsish causing Reflect.deleteProperty to evaluate to false"],"goal":"verify pkg:npm/bare-env@3.0.1","kind":"HOW","packages":["pkg:npm/bare-env@3.0.1"],"schemaVersion":1,"symbols":["env"]},"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-env@3.0.1"],"schemaVersion":1,"subject":"pkg:npm/bare-env@3.0.1","symbols":["env"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-bare-env",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-bare-env",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "bare-env": "3.0.1"
      }
    },
    "node_modules/bare-env": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/bare-env/-/bare-env-3.0.1.tgz",
      "integrity": "sha512-BdoLvnzaWR0YyyJreEx4zG2Od0AC/s9JSZ+EXyMZKunpn8zEgR/dGv37hdFUaY1bjDkcRKvcKkFyJIwlJ0CaYA==",
      "license": "Apache-2.0",
      "dependencies": {
        "bare-os": "^3.0.1"
      }
    },
    "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-env",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "bare-env": "3.0.1"
  }
}

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

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

assert.equal(pkg.name, 'bare-env', 'Package name must be bare-env');
assert.equal(pkg.version, '3.0.1', 'Package version must be 3.0.1');
assert.equal(pkg.license, 'Apache-2.0', 'Package license must be Apache-2.0');
assert.deepEqual(pkg.dependencies, { 'bare-os': '^3.0.1' }, 'Package must depend on bare-os ^3.0.1');

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['./package'], './package.json', 'Package export must point to ./package.json');

assert.deepEqual(
  pkg.files,
  ['index.js', 'index.d.ts'],
  'Package files array must contain expected source 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('interface Env'), 'index.d.ts must declare interface Env');
assert.ok(indexDts.includes('[key: string]: string | undefined'), 'index.d.ts must declare string index signature');
assert.ok(indexDts.includes('declare const env: Env'), 'index.d.ts must declare const env');
assert.ok(indexDts.includes('export = env'), 'index.d.ts must export env');

// 3. Verify JavaScript implementation and Proxy traps
const indexJsPath = path.join(pkgDir, 'index.js');
assert.ok(fs.existsSync(indexJsPath), 'index.js must exist');
const indexJsCode = fs.readFileSync(indexJsPath, 'utf8');

assert.ok(indexJsCode.includes("require('bare-os')"), 'index.js must require bare-os');
assert.ok(indexJsCode.includes('new Proxy(Object.create(null)'), 'index.js must instantiate Proxy over null prototype');

// Test Proxy behaviour in isolated environment with bare-os mock
const mockStore = new Map();
const mockBareOs = {
  getEnvKeys: () => Array.from(mockStore.keys()),
  getEnv: (name) => mockStore.get(name),
  hasEnv: (name) => mockStore.has(name),
  setEnv: (name, val) => { mockStore.set(name, val); },
  unsetEnv: (name) => { mockStore.delete(name); }
};

const cjsModule = { exports: {} };
const customRequire = (id) => {
  if (id === 'bare-os') return mockBareOs;
  return require(id);
};
const fn = new Function('require', 'module', 'exports', indexJsCode);
fn(customRequire, cjsModule, cjsModule.exports);

const env = cjsModule.exports;

// 4. Test setting, getting, and checking existence of environment variables
env.PORT = '8080';
assert.equal(env.PORT, '8080', 'Getting set property must return value');
assert.equal(mockStore.get('PORT'), '8080', 'Setting property must store value in bare-os');
assert.equal('PORT' in env, true, 'in operator must return true for set variable');
assert.equal('NON_EXISTENT_VAR' in env, false, 'in operator must return false for missing variable');

// 5. Test type coercion for number and boolean values
env.TIMEOUT = 5000;
assert.equal(env.TIMEOUT, '5000', 'Number must be coerced to string');
assert.equal(mockStore.get('TIMEOUT'), '5000', 'Stored value must be string');

env.FEATURE_FLAG = true;
assert.equal(env.FEATURE_FLAG, 'true', 'Boolean true must be coerced to string');

env.DEBUG_MODE = false;
assert.equal(env.DEBUG_MODE, 'false', 'Boolean false must be coerced to string');

// 6. Test rejection of non-primitive types
assert.throws(
  () => { env.INVALID_OBJ = { key: 'value' }; },
  /Environment variable must be of type string, number, or boolean/,
  'Setting object must throw validation error'
);

assert.throws(
  () => { env.INVALID_ARR = [1, 2, 3]; },
  /Environment variable must be of type string, number, or boolean/,
  'Setting array must throw validation error'
);

assert.throws(
  () => { env.INVALID_FN = () => {}; },
  /Environment variable must be of type string, number, or boolean/,
  'Setting function must throw validation error'
);

assert.throws(
  () => { env.INVALID_SYM = Symbol('env'); },
  /Environment variable must be of type string, number, or boolean/,
  'Setting symbol must throw validation error'
);

// 7. Test ownKeys trap and Object.keys enumeration
const envKeys = Object.keys(env);
assert.deepEqual(
  envKeys.sort(),
  ['DEBUG_MODE', 'FEATURE_FLAG', 'PORT', 'TIMEOUT'].sort(),
  'Object.keys must enumerate all active environment variables'
);

// 8. Test getOwnPropertyDescriptor trap
const descriptor = Object.getOwnPropertyDescriptor(env, 'PORT');
assert.deepEqual(descriptor, {
  value: '8080',
  enumerable: true,
  configurable: true,
  writable: true
}, 'getOwnPropertyDescriptor must return full enumerable, configurable, writable descriptor');

// 9. Test deleteProperty trap
// Strict mode delete throws because deleteProperty trap in bare-env does not return true
assert.throws(
  () => { delete env.PORT; },
  TypeError,
  'Strict mode delete must throw TypeError due to missing explicit return in deleteProperty trap'
);
// Verify that despite the falsish return, unsetEnv was executed
assert.equal(mockStore.has('PORT'), false, 'Variable must be deleted from backing store');
assert.equal(env.PORT, undefined, 'Deleted variable must return undefined');
assert.equal('PORT' in env, false, 'Deleted variable must not be in env');

// Reflect.deleteProperty returns false without throwing
const deletedTimeout = Reflect.deleteProperty(env, 'TIMEOUT');
assert.equal(deletedTimeout, false, 'Reflect.deleteProperty returns false for bare-env proxy');
assert.equal(mockStore.has('TIMEOUT'), false, 'Reflect.deleteProperty must unset variable in backing store');

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