@malept/flatpak-bundler 0.4.0: bundle

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 @malept/flatpak-bundler.bundle in pkg:npm/%40malept/flatpak-bundler@0.4.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40malept/flatpak-bundler@0.4.0
Demonstrate these symbols/APIs:
  - @malept/flatpak-bundler.bundle

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:ff46528ff8f7cf19b15c14a36073dcdb7bf11ec168fb5c50599f8cc8b031a1fa","contract":["bundle is exported as an async function on the package namespace","bundle rejects with an error when flatpak host tools are missing or fail","bundle translates architecture strings using translateArch in build options","bundle applies default paths for build-dir, repo-dir, and manifest-path","bundle normalizes manifest appId to id in output manifest","bundle writes manifest configuration as formatted JSON to working directory","bundle executes build pipeline, copies files, and creates symlinks before returning resolved options"],"goal":"verify @malept/flatpak-bundler.bundle in pkg:npm/%40malept/flatpak-bundler@0.4.0","kind":"HOW","packages":["pkg:npm/%40malept/flatpak-bundler@0.4.0"],"schemaVersion":1,"symbols":["@malept/flatpak-bundler.bundle"]},"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/%40malept/flatpak-bundler@0.4.0"],"schemaVersion":1,"subject":"pkg:npm/%40malept/flatpak-bundler@0.4.0","symbols":["@malept/flatpak-bundler.bundle"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-flatpak-bundler-bundle",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-flatpak-bundler-bundle",
      "version": "1.0.0",
      "dependencies": {
        "@malept/flatpak-bundler": "0.4.0"
      }
    },
    "node_modules/@malept/flatpak-bundler": {
      "version": "0.4.0",
      "resolved": "https://registry.npmjs.org/@malept/flatpak-bundler/-/flatpak-bundler-0.4.0.tgz",
      "integrity": "sha512-9QOtNffcOF/c1seMCDnjckb3R9WHcG34tky+FHpNKKCW0wc/scYLwMtO+ptyGUfMW0/b/n4qRiALlaFHc9Oj7Q==",
      "license": "MIT",
      "dependencies": {
        "debug": "^4.1.1",
        "fs-extra": "^9.0.0",
        "lodash": "^4.17.15",
        "tmp-promise": "^3.0.2"
      },
      "engines": {
        "node": ">= 10.0.0"
      }
    },
    "node_modules/at-least-node": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/at-least-node/-/at-least-node-1.0.0.tgz",
      "integrity": "sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg==",
      "license": "ISC",
      "engines": {
        "node": ">= 4.0.0"
      }
    },
    "node_modules/debug": {
      "version": "4.4.3",
      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
      "license": "MIT",
      "dependencies": {
        "ms": "^2.1.3"
      },
      "engines": {
        "node": ">=6.0"
      },
      "peerDependenciesMeta": {
        "supports-color": {
          "optional": true
        }
      }
    },
    "node_modules/fs-extra": {
      "version": "9.1.0",
      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-9.1.0.tgz",
      "integrity": "sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ==",
      "license": "MIT",
      "dependencies": {
        "at-least-node": "^1.0.0",
        "graceful-fs": "^4.2.0",
        "jsonfile": "^6.0.1",
        "universalify": "^2.0.0"
      },
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/graceful-fs": {
      "version": "4.2.11",
      "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
      "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
      "license": "ISC"
    },
    "node_modules/jsonfile": {
      "version": "6.2.1",
      "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.1.tgz",
      "integrity": "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==",
      "license": "MIT",
      "dependencies": {
        "universalify": "^2.0.0"
      },
      "optionalDependencies": {
        "graceful-fs": "^4.1.6"
      }
    },
    "node_modules/lodash": {
      "version": "4.18.1",
      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz",
      "integrity": "sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==",
      "license": "MIT"
    },
    "node_modules/ms": {
      "version": "2.1.3",
      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
      "license": "MIT"
    },
    "node_modules/tmp": {
      "version": "0.2.7",
      "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.2.7.tgz",
      "integrity": "sha512-e0votIpp4Uo2AJYSzVHV6xCcawuiez3DzqDAbrTc3YxBkplN6e+dM13ZeIcZnDg/QpSuU2zfZ3rzwY8ukEnaXw==",
      "license": "MIT",
      "engines": {
        "node": ">=14.14"
      }
    },
    "node_modules/tmp-promise": {
      "version": "3.0.3",
      "resolved": "https://registry.npmjs.org/tmp-promise/-/tmp-promise-3.0.3.tgz",
      "integrity": "sha512-RwM7MoPojPxsOBYnyd2hy0bxtIlVrihNs9pj5SUvY8Zz1sQcQG2tG1hSr8PDxfgEB8RNKDhqbIlroIarSNDNsQ==",
      "license": "MIT",
      "dependencies": {
        "tmp": "^0.2.0"
      }
    },
    "node_modules/universalify": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz",
      "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==",
      "license": "MIT",
      "engines": {
        "node": ">= 10.0.0"
      }
    }
  }
}

{
  "name": "sample-flatpak-bundler-bundle",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for @malept/flatpak-bundler.bundle",
  "type": "module",
  "dependencies": {
    "@malept/flatpak-bundler": "0.4.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @malept/flatpak-bundler.bundle in pkg:npm/%40malept/flatpak-bundler@0.4.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40malept/flatpak-bundler@0.4.0"
  ],
  "symbols": [
    "@malept/flatpak-bundler.bundle"
  ]
}

import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import flatpakBundler from '@malept/flatpak-bundler';

const { bundle } = flatpakBundler;

function createMockBinaries(targetDir) {
  const binDir = path.join(targetDir, 'bin');
  fs.mkdirSync(binDir, { recursive: true });

  const fbScript = `#!/bin/sh
if [ "$1" = "--version" ]; then
  echo "flatpak-builder 1.2.0"
  exit 0
fi
exit 0
`;
  fs.writeFileSync(path.join(binDir, 'flatpak-builder'), fbScript, { mode: 0o755 });

  const flatpakScript = `#!/bin/sh
exit 0
`;
  fs.writeFileSync(path.join(binDir, 'flatpak'), flatpakScript, { mode: 0o755 });

  return binDir;
}

// 1. bundle is exported as an async function on the package namespace
{
  assert.strictEqual(typeof bundle, 'function', 'bundle must be a function');
  assert.strictEqual(bundle.constructor.name, 'AsyncFunction', 'bundle must be an async function');
}

// 2. bundle rejects with an error when flatpak host tools are missing or fail
{
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fb-contract-fail-'));
  try {
    await assert.rejects(
      async () => {
        await bundle(
          {
            id: 'org.example.MissingToolsApp',
            runtime: 'org.freedesktop.Platform',
            runtimeVersion: '23.08',
            sdk: 'org.freedesktop.Sdk'
          },
          {
            workingDir: tempDir,
            arch: 'x64'
          }
        );
      },
      (err) => {
        assert.ok(err instanceof Error, 'bundle must reject with an Error');
        return true;
      }
    );
  } finally {
    fs.rmSync(tempDir, { recursive: true, force: true });
  }
}

// 3. bundle translates architecture strings using translateArch in build options
{
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fb-contract-arch-'));
  const binDir = createMockBinaries(tempDir);
  const workDir = path.join(tempDir, 'work');
  fs.mkdirSync(workDir, { recursive: true });

  const originalPath = process.env.PATH;
  process.env.PATH = `${binDir}:${originalPath}`;

  try {
    const manifest = {
      id: 'org.example.ArchApp',
      runtime: 'org.freedesktop.Platform',
      runtimeVersion: '23.08',
      sdk: 'org.freedesktop.Sdk'
    };

    const resX64 = await bundle(manifest, { workingDir: workDir, arch: 'x64' });
    assert.strictEqual(resX64.arch, 'x86_64', 'x64 should translate to x86_64');

    const resIa32 = await bundle(manifest, { workingDir: workDir, arch: 'ia32' });
    assert.strictEqual(resIa32.arch, 'i386', 'ia32 should translate to i386');

    const resArmv7l = await bundle(manifest, { workingDir: workDir, arch: 'armv7l' });
    assert.strictEqual(resArmv7l.arch, 'arm', 'armv7l should translate to arm');

    const resArm64 = await bundle(manifest, { workingDir: workDir, arch: 'arm64' });
    assert.strictEqual(resArm64.arch, 'arm64', 'arm64 should remain unchanged');
  } finally {
    process.env.PATH = originalPath;
    fs.rmSync(tempDir, { recursive: true, force: true });
  }
}

// 4. bundle applies default paths for build-dir, repo-dir, and manifest-path
{
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fb-contract-defaults-'));
  const binDir = createMockBinaries(tempDir);
  const workDir = path.join(tempDir, 'work');
  fs.mkdirSync(workDir, { recursive: true });

  const originalPath = process.env.PATH;
  process.env.PATH = `${binDir}:${originalPath}`;

  try {
    const manifest = {
      id: 'org.example.DefaultsApp',
      runtime: 'org.freedesktop.Platform',
      runtimeVersion: '23.08',
      sdk: 'org.freedesktop.Sdk'
    };

    const finalOptions = await bundle(manifest, { workingDir: workDir });
    assert.strictEqual(finalOptions['working-dir'], path.resolve(workDir));
    assert.strictEqual(finalOptions['build-dir'], path.resolve(path.join(workDir, 'build')));
    assert.strictEqual(finalOptions['repo-dir'], path.resolve(path.join(workDir, 'repo')));
    assert.strictEqual(finalOptions['manifest-path'], path.resolve(path.join(workDir, 'manifest.json')));
    assert.strictEqual(finalOptions['clean-tmpdirs'], true);
    assert.strictEqual(finalOptions['auto-install-runtime'], false);
    assert.strictEqual(finalOptions['auto-install-sdk'], false);
    assert.strictEqual(finalOptions['auto-install-base'], false);
  } finally {
    process.env.PATH = originalPath;
    fs.rmSync(tempDir, { recursive: true, force: true });
  }
}

// 5. bundle normalizes manifest appId to id in output manifest
{
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fb-contract-appid-'));
  const binDir = createMockBinaries(tempDir);
  const workDir = path.join(tempDir, 'work');
  fs.mkdirSync(workDir, { recursive: true });

  const originalPath = process.env.PATH;
  process.env.PATH = `${binDir}:${originalPath}`;

  try {
    const manifest = {
      appId: 'org.example.NormalizedIdApp',
      runtime: 'org.freedesktop.Platform',
      runtimeVersion: '23.08',
      sdk: 'org.freedesktop.Sdk'
    };

    const finalOptions = await bundle(manifest, { workingDir: workDir });
    const written = JSON.parse(fs.readFileSync(finalOptions['manifest-path'], 'utf-8'));
    assert.strictEqual(written.id, 'org.example.NormalizedIdApp', 'appId should normalize to id');
  } finally {
    process.env.PATH = originalPath;
    fs.rmSync(tempDir, { recursive: true, force: true });
  }
}

// 6. bundle writes manifest configuration as formatted JSON to working directory
{
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fb-contract-writejson-'));
  const binDir = createMockBinaries(tempDir);
  const workDir = path.join(tempDir, 'work');
  fs.mkdirSync(workDir, { recursive: true });

  const originalPath = process.env.PATH;
  process.env.PATH = `${binDir}:${originalPath}`;

  try {
    const manifest = {
      id: 'org.example.WriteJsonApp',
      runtime: 'org.freedesktop.Platform',
      runtimeVersion: '23.08',
      sdk: 'org.freedesktop.Sdk',
      branch: 'master'
    };

    const finalOptions = await bundle(manifest, { workingDir: workDir });
    assert.ok(fs.existsSync(finalOptions['manifest-path']), 'manifest file must exist on disk');

    const content = fs.readFileSync(finalOptions['manifest-path'], 'utf-8');
    const parsed = JSON.parse(content);
    assert.strictEqual(parsed.id, 'org.example.WriteJsonApp');
    assert.strictEqual(parsed.runtime, 'org.freedesktop.Platform');
    assert.strictEqual(parsed['runtime-version'], '23.08');
    assert.strictEqual(parsed.sdk, 'org.freedesktop.Sdk');
    assert.strictEqual(parsed.branch, 'master');
  } finally {
    process.env.PATH = originalPath;
    fs.rmSync(tempDir, { recursive: true, force: true });
  }
}

// 7. bundle executes build pipeline, copies files, and creates symlinks before returning resolved options
{
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fb-contract-pipeline-'));
  const binDir = createMockBinaries(tempDir);
  const workDir = path.join(tempDir, 'work');
  fs.mkdirSync(workDir, { recursive: true });

  const originalPath = process.env.PATH;
  process.env.PATH = `${binDir}:${originalPath}`;

  const sourceFile = path.join(tempDir, 'input.txt');
  fs.writeFileSync(sourceFile, 'bundler content test');

  try {
    const manifest = {
      id: 'org.example.PipelineApp',
      runtime: 'org.freedesktop.Platform',
      runtimeVersion: '23.08',
      sdk: 'org.freedesktop.Sdk'
    };

    const bundlePath = path.join(tempDir, 'output.flatpak');
    const options = {
      workingDir: workDir,
      arch: 'x64',
      bundlePath,
      files: [
        [sourceFile, '/share/input.txt']
      ],
      symlinks: [
        ['/share/input.txt', '/bin/input-link']
      ],
      cleanTmpdirs: false
    };

    const finalOptions = await bundle(manifest, options);

    assert.strictEqual(finalOptions.arch, 'x86_64');
    assert.strictEqual(finalOptions['bundle-path'], path.resolve(bundlePath));

    const copiedFile = path.join(finalOptions['build-dir'], 'files', '/share/input.txt');
    assert.ok(fs.existsSync(copiedFile), 'copied file must exist at build destination');
    assert.strictEqual(fs.readFileSync(copiedFile, 'utf-8'), 'bundler content test');

    const symlinkFile = path.join(finalOptions['build-dir'], 'files', '/bin/input-link');
    assert.ok(fs.lstatSync(symlinkFile).isSymbolicLink(), 'symlink destination must be a symbolic link');
    assert.strictEqual(fs.readlinkSync(symlinkFile), '/app/share/input.txt');
  } finally {
    process.env.PATH = originalPath;
    fs.rmSync(tempDir, { recursive: true, force: true });
  }
}

console.log('All 7 contract assertions passed successfully.');