bare-bundle 1.10.0: Bundle.from

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-bundle@1.10.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/bare-bundle@1.10.0
Demonstrate these symbols/APIs:
  - Bundle.from

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:5d35ae42da64397acbef8893ab76a405b3cfeaba825b33001d561358a7918d0a","contract":["Bundle.from deserializes a Buffer into a Bundle instance restoring all files, modes, and metadata","Bundle.from parses bundle Buffer containing a shebang prefix line","Bundle.from deserializes a bundle from string representation","Bundle.from throws INVALID_BUNDLE_HEADER when input buffer has malformed header","Bundle.isBundle returns true for Bundle instances and false for other values","Bundle.prototype.write options set main, alias, addon, and asset properties"],"goal":"verify pkg:npm/bare-bundle@1.10.0","kind":"HOW","packages":["pkg:npm/bare-bundle@1.10.0"],"schemaVersion":1,"symbols":["Bundle.from"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/bare-bundle@1.10.0"],"schemaVersion":1,"subject":"pkg:npm/bare-bundle@1.10.0","symbols":["Bundle.from"],"verifierAdapter":"node-typescript@1"}

import Bundle from 'bare-bundle';

/**
 * Creates and serializes a bundle to a Buffer.
 * @param {Array<{path: string, content: string|Buffer, options?: object}>} files
 * @param {object} [metadata]
 * @returns {Buffer}
 */
export function serializeBundle(files = [], metadata = {}) {
  const bundle = new Bundle();
  if (metadata.id) bundle.id = metadata.id;
  for (const file of files) {
    bundle.write(file.path, file.content, file.options);
  }
  return bundle.toBuffer();
}

/**
 * Deserializes a bundle from Buffer or string using Bundle.from.
 * @param {Buffer|string} input
 * @returns {Bundle}
 */
export function deserializeBundle(input) {
  return Bundle.from(input);
}

/**
 * Checks whether a given value is a Bundle instance.
 * @param {unknown} value
 * @returns {boolean}
 */
export function checkIsBundle(value) {
  return Bundle.isBundle(value);
}

export default Bundle;
export { Bundle };

{
  "name": "sample-bare-bundle",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-bare-bundle",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "bare-bundle": "1.10.0"
      }
    },
    "node_modules/bare-bundle": {
      "version": "1.10.0",
      "resolved": "https://registry.npmjs.org/bare-bundle/-/bare-bundle-1.10.0.tgz",
      "integrity": "sha512-4LVlnJAHr00Hh6Vu6ZUJS38rcEtJT3b3vChXSsBsJ2mk1TN0lQ+gzd+Dw5L0aV7uqDZv84smuwW+O02X7PfDlw==",
      "license": "Apache-2.0",
      "peerDependencies": {
        "bare-buffer": "*",
        "bare-url": "*"
      },
      "peerDependenciesMeta": {
        "bare-buffer": {
          "optional": true
        },
        "bare-url": {
          "optional": true
        }
      }
    }
  }
}

{
  "name": "sample-bare-bundle",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "bare-bundle": "1.10.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/bare-bundle@1.10.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/bare-bundle@1.10.0"
  ],
  "symbols": [
    "Bundle.from"
  ]
}

import assert from 'node:assert/strict';
import Bundle, { serializeBundle, deserializeBundle, checkIsBundle } from '../index.js';

// 1. Bundle.from deserializes a Buffer into a Bundle instance restoring all files, modes, and metadata
{
  const original = new Bundle();
  original.id = 'test-bundle';
  original.write('/index.js', 'console.log("hello");', { main: true, mode: 0o755 });
  original.write('/data.txt', 'sample data', { mode: 0o644 });

  const buffer = serializeBundle([
    { path: '/index.js', content: 'console.log("hello");', options: { main: true, mode: 0o755 } },
    { path: '/data.txt', content: 'sample data', options: { mode: 0o644 } }
  ], { id: 'test-bundle' });

  const restored = deserializeBundle(buffer);

  assert.equal(Bundle.isBundle(restored), true);
  assert.equal(checkIsBundle(restored), true);
  assert.equal(restored.id, 'test-bundle');
  assert.equal(restored.main, '/index.js');
  assert.equal(restored.exists('/index.js'), true);
  assert.equal(restored.exists('/data.txt'), true);
  assert.equal(restored.exists('/nonexistent.js'), false);
  assert.equal(restored.read('/index.js').toString('utf8'), 'console.log("hello");');
  assert.equal(restored.read('/data.txt').toString('utf8'), 'sample data');
  assert.equal(restored.mode('/index.js'), 0o755);
  assert.equal(restored.mode('/data.txt'), 0o644);
  assert.equal(restored.size('/data.txt'), 11);
}

// 2. Bundle.from parses bundle Buffer containing a shebang prefix line
{
  const original = new Bundle();
  original.write('/bin/cli.js', 'process.exit(0);', { mode: 0o755 });
  const rawBuf = original.toBuffer();
  const shebang = Buffer.from('#!/usr/bin/env bare\n');
  const bufferWithShebang = Buffer.concat([shebang, rawBuf]);

  const restored = Bundle.from(bufferWithShebang);
  assert.equal(Bundle.isBundle(restored), true);
  assert.equal(restored.exists('/bin/cli.js'), true);
  assert.equal(restored.read('/bin/cli.js').toString('utf8'), 'process.exit(0);');
  assert.equal(restored.mode('/bin/cli.js'), 0o755);
}

// 3. Bundle.from deserializes a bundle from string representation
{
  const original = new Bundle();
  original.write('/greeting.txt', 'Hello World', { mode: 0o644 });
  const buf = original.toBuffer();
  const str = buf.toString('utf8');

  const restored = Bundle.from(str);
  assert.equal(Bundle.isBundle(restored), true);
  assert.equal(restored.exists('/greeting.txt'), true);
  assert.equal(restored.read('/greeting.txt').toString('utf8'), 'Hello World');
}

// 4. Bundle.from throws INVALID_BUNDLE_HEADER when input buffer has malformed header
{
  const corruptBuffer = Buffer.from('123{"invalid":json');
  assert.throws(
    () => {
      Bundle.from(corruptBuffer);
    },
    (err) => {
      assert.equal(err.code, 'INVALID_BUNDLE_HEADER');
      return true;
    }
  );
}

// 5. Bundle.isBundle returns true for Bundle instances and false for other values
{
  const bundle = new Bundle();
  assert.equal(Bundle.isBundle(bundle), true);
  assert.equal(checkIsBundle(bundle), true);
  assert.equal(Bundle.isBundle(Bundle.from(bundle.toBuffer())), true);
  assert.equal(Bundle.isBundle(null), false);
  assert.equal(Bundle.isBundle(undefined), false);
  assert.equal(Bundle.isBundle({}), false);
  assert.equal(Bundle.isBundle('bundle'), false);
  assert.equal(Bundle.isBundle(123), false);
}

// 6. Bundle.prototype.write options set main, alias, addon, and asset properties
{
  const bundle = new Bundle();
  bundle.write('/app.js', 'export default 1;', { main: true, alias: 'main-app' });
  bundle.write('/native.bare', 'native addon binary', { addon: true });
  bundle.write('/image.png', 'png bytes', { asset: true });

  assert.equal(bundle.main, '/app.js');
  assert.equal(bundle.imports['main-app'], '/app.js');
  assert.ok(bundle.addons.includes('/native.bare'));
  assert.ok(bundle.assets.includes('/image.png'));
}

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