@le-space/rootfs 0.1.3

package/README.md

@@ -0,0 +1,16 @@
+# @shared-aleph/rootfs
+
+Shared rootfs contract parsing, reference profile assets, and build helpers.
+
+## Current scope
+
+- typed parsing and validation of rootfs contract JSON
+- shell-env mapping compatible with the existing UC rootfs builder
+- copied `uc-go-peer` reference contract and guest asset set
+
+## Reference assets
+
+The first shared reference profile lives under:
+
+- `reference/uc-go-peer/contract.json`
+- `reference/uc-go-peer/rootfs/*`

package/index.d.ts

@@ -0,0 +1,249 @@
+interface RootfsContractPort {
+    port: number;
+    tcp?: boolean;
+    udp?: boolean;
+    purpose?: string;
+}
+interface RootfsContractRootfs {
+    profile: string;
+    installMode: string;
+    installDir: string;
+    binaryPath: string;
+    dataDir: string;
+    envFile: string;
+}
+interface RootfsContractServices {
+    bootstrap: string;
+    main: string;
+    autotlsRefresh: string;
+}
+interface RootfsContractManifest {
+    copyTarget: string;
+    notes?: string;
+}
+interface RootfsContractSource {
+    repository?: string;
+    subdirectory?: string;
+}
+interface RootfsContract {
+    schemaVersion: number;
+    id: string;
+    displayName?: string;
+    source?: RootfsContractSource;
+    rootfs: RootfsContractRootfs;
+    services: RootfsContractServices;
+    ports: RootfsContractPort[];
+    manifest: RootfsContractManifest;
+}
+interface RootfsContractState {
+    contract: RootfsContract | null;
+    valid: boolean;
+    errors: string[];
+}
+declare function validateRootfsContract(input: unknown): RootfsContractState;
+declare function parseRootfsContract(input: string | unknown): RootfsContract;
+declare function readRootfsContractFile(path: string): Promise<RootfsContract>;
+declare function contractShellEnv(contract: RootfsContract, contractPath?: string): Record<string, string>;
+declare function referenceProfileRoot(profile: string): string;
+declare function referenceProfileContractPath(profile: string): string;
+declare function referenceProfileRootfsDir(profile: string): string;
+
+type RootfsBuildDriver = 'auto' | 'host' | 'docker';
+interface RootfsBuildOptions {
+    projectDir: string;
+    alephDir?: string;
+    outDir?: string;
+    contractPath?: string;
+    driver?: RootfsBuildDriver;
+    rootfsSizeMiB?: number;
+    rootfsImageSize?: string;
+    rootfsVersion?: string;
+    channel?: string;
+    skipUpload?: boolean;
+    skipBuild?: boolean;
+    ipfsAddUrl?: string;
+    ipfsGatewayUrl?: string;
+    alephApiHost?: string;
+    alephMessageWaitAttempts?: number;
+    alephMessageWaitDelaySeconds?: number;
+    alephPinAttempts?: number;
+    alephPinDelaySeconds?: number;
+    ipfsGatewayWaitAttempts?: number;
+    ipfsGatewayWaitDelaySeconds?: number;
+    gitShortSha?: string | null;
+    now?: Date;
+}
+interface RootfsBuildPlan {
+    contract: RootfsContract;
+    contractPath: string;
+    projectDir: string;
+    alephDir: string;
+    outDir: string;
+    driver: RootfsBuildDriver;
+    rootfsSizeMiB: number;
+    rootfsImageSize: string;
+    rootfsVersion: string;
+    channel: string;
+    skipUpload: boolean;
+    skipBuild: boolean;
+    ipfsAddUrl: string;
+    ipfsGatewayUrl: string;
+    alephApiHost: string;
+    alephMessageWaitAttempts: number;
+    alephMessageWaitDelaySeconds: number;
+    alephPinAttempts: number;
+    alephPinDelaySeconds: number;
+    ipfsGatewayWaitAttempts: number;
+    ipfsGatewayWaitDelaySeconds: number;
+    manifestPath: string;
+    latestManifestPath: string | null;
+    versionedManifestPath: string | null;
+    imagePath: string;
+    baseImagePath: string;
+    binaryPath: string;
+}
+declare function deriveRootfsVersion(options?: Pick<RootfsBuildOptions, 'rootfsVersion' | 'gitShortSha' | 'now'>): string;
+declare function createRootfsBuildPlan(contract: RootfsContract, options: RootfsBuildOptions): RootfsBuildPlan;
+declare function rootfsBuildShellEnv(plan: RootfsBuildPlan): Record<string, string>;
+
+interface RootfsManifest {
+    profile: string;
+    version: string;
+    rootfsInstallStrategy: string;
+    requiresBootstrapNetwork: boolean;
+    bootstrapSummary: string;
+    rootfsSourceSizeBytes?: number;
+    requiredPortForwards: RootfsContract["ports"];
+    rootfsCid?: string;
+    rootfsItemHash?: string;
+    rootfsSizeMiB: number;
+    createdAt: string;
+    notes: string;
+}
+interface RootfsManifestOptions {
+    createdAt?: string;
+    rootfsCid?: string;
+    rootfsItemHash?: string;
+    rootfsSourceSizeBytes?: number;
+}
+interface RootfsManifestOutputPaths {
+    primaryPath: string;
+    copyTargetPath?: string;
+    versionedTargetPath?: string;
+}
+declare function rootfsSourceSizeBytesFromIpfsAddResponse(content: string): number | undefined;
+declare function createRootfsManifest(plan: RootfsBuildPlan, contract: RootfsContract, options?: RootfsManifestOptions): RootfsManifest;
+declare function resolveRootfsManifestOutputPaths(plan: RootfsBuildPlan): RootfsManifestOutputPaths;
+declare function serializeRootfsManifest(manifest: RootfsManifest): string;
+
+interface RootfsToolchainAvailability {
+    hasDocker: boolean;
+    dockerDaemonRunning?: boolean;
+    hasVirtCustomize: boolean;
+    githubActions?: boolean;
+}
+interface RootfsCommandPlan {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+    workdir?: string;
+}
+interface RootfsExecutionPlan {
+    mode: "host" | "docker";
+    reason: string;
+    referenceRootfsDir: string;
+    prepareCommand?: RootfsCommandPlan;
+    runCommand: RootfsCommandPlan;
+}
+interface RootfsExecutionPlanOptions {
+    referenceRootfsDir?: string;
+    projectMountPath?: string;
+    rootfsMountPath?: string;
+    dockerImageTag?: string;
+}
+declare function createHostRootfsExecutionPlan(plan: RootfsBuildPlan, options?: RootfsExecutionPlanOptions): RootfsExecutionPlan;
+declare function createDockerRootfsExecutionPlan(plan: RootfsBuildPlan, options?: RootfsExecutionPlanOptions): RootfsExecutionPlan;
+declare function selectRootfsExecutionPlan(plan: RootfsBuildPlan, availability: RootfsToolchainAvailability, options?: RootfsExecutionPlanOptions): RootfsExecutionPlan;
+
+interface RootfsIpfsAddEntry {
+    Name?: string;
+    Hash?: string;
+    Size?: string | number;
+}
+interface RootfsStoreMessageResponse {
+    item_hash: string;
+}
+interface RootfsPublicationArtifacts {
+    ipfsAddResponsePath: string;
+    storeMessagePath: string;
+    storeMessageStderrPath: string;
+}
+interface RootfsPublicationResult {
+    cid: string;
+    itemHash: string;
+    sourceSizeBytes?: number;
+}
+interface RootfsStoreMessageStatus {
+    status: string;
+    rejectionSummary?: string;
+}
+declare function publicationArtifacts(plan: RootfsBuildPlan): RootfsPublicationArtifacts;
+declare function parseIpfsAddResponse(content: string): RootfsIpfsAddEntry[];
+declare function extractRootfsCid(entries: RootfsIpfsAddEntry[]): string;
+declare function extractRootfsSourceSizeBytes(entries: RootfsIpfsAddEntry[]): number | undefined;
+declare function parseStoreMessageResponse(content: string): RootfsStoreMessageResponse;
+declare function summarizeStoreMessageFailure(stderrContent: string): string;
+declare function parseStoreMessageStatus(content: string): RootfsStoreMessageStatus;
+declare function createRootfsPublicationResult(ipfsAddContent: string, storeMessageContent: string): RootfsPublicationResult;
+
+interface RootfsBuildPipeline {
+    buildPlan: RootfsBuildPlan;
+    executionPlan: RootfsExecutionPlan;
+    publicationArtifacts: RootfsPublicationArtifacts;
+    manifestPaths: RootfsManifestOutputPaths;
+}
+interface RootfsFinalizeResult {
+    manifest: RootfsManifest;
+    manifestJson: string;
+    manifestPaths: RootfsManifestOutputPaths;
+    publication?: RootfsPublicationResult;
+}
+interface RootfsFinalizeOptions extends RootfsManifestOptions {
+    ipfsAddResponseContent?: string;
+    storeMessageContent?: string;
+}
+declare function createRootfsBuildPipeline(buildPlan: RootfsBuildPlan, availability: RootfsToolchainAvailability, options?: RootfsExecutionPlanOptions): RootfsBuildPipeline;
+declare function createHostRootfsBuildPipeline(buildPlan: RootfsBuildPlan, options?: RootfsExecutionPlanOptions): RootfsBuildPipeline;
+declare function createDockerRootfsBuildPipeline(buildPlan: RootfsBuildPlan, options?: RootfsExecutionPlanOptions): RootfsBuildPipeline;
+declare function finalizeRootfsBuildPipeline(buildPlan: RootfsBuildPlan, options?: RootfsFinalizeOptions): RootfsFinalizeResult;
+
+interface RootfsExecutedCommand {
+    command: string;
+    args: string[];
+    workdir?: string;
+    env?: Record<string, string>;
+}
+interface RootfsCommandRunner {
+    run(command: RootfsExecutedCommand): Promise<void>;
+}
+interface RootfsFileReader {
+    readText(path: string): Promise<string>;
+}
+interface RootfsExecutorDependencies extends RootfsCommandRunner, RootfsFileReader {
+}
+interface RootfsExecutionResult {
+    pipeline: RootfsBuildPipeline;
+    executedCommands: RootfsExecutedCommand[];
+}
+interface RootfsPublishExecutionResult extends RootfsExecutionResult {
+    finalized: RootfsFinalizeResult;
+}
+interface RootfsPublishOptions extends RootfsExecutionPlanOptions {
+    createdAt?: string;
+    referenceRootfsDir?: string;
+}
+declare function createRootfsScriptCommand(buildPlan: RootfsBuildPlan, referenceRootfsDir?: string): RootfsExecutedCommand;
+declare function buildRootfs(buildPlan: RootfsBuildPlan, deps: RootfsCommandRunner, availability: RootfsToolchainAvailability, options?: RootfsExecutionPlanOptions): Promise<RootfsExecutionResult>;
+declare function publishRootfs(buildPlan: RootfsBuildPlan, deps: RootfsExecutorDependencies, options?: RootfsPublishOptions): Promise<RootfsPublishExecutionResult>;
+
+export { type RootfsBuildDriver, type RootfsBuildOptions, type RootfsBuildPipeline, type RootfsBuildPlan, type RootfsCommandPlan, type RootfsCommandRunner, type RootfsContract, type RootfsContractManifest, type RootfsContractPort, type RootfsContractRootfs, type RootfsContractServices, type RootfsContractSource, type RootfsContractState, type RootfsExecutedCommand, type RootfsExecutionPlan, type RootfsExecutionPlanOptions, type RootfsExecutionResult, type RootfsExecutorDependencies, type RootfsFileReader, type RootfsFinalizeOptions, type RootfsFinalizeResult, type RootfsIpfsAddEntry, type RootfsManifest, type RootfsManifestOptions, type RootfsManifestOutputPaths, type RootfsPublicationArtifacts, type RootfsPublicationResult, type RootfsPublishExecutionResult, type RootfsPublishOptions, type RootfsStoreMessageResponse, type RootfsStoreMessageStatus, type RootfsToolchainAvailability, buildRootfs, contractShellEnv, createDockerRootfsBuildPipeline, createDockerRootfsExecutionPlan, createHostRootfsBuildPipeline, createHostRootfsExecutionPlan, createRootfsBuildPipeline, createRootfsBuildPlan, createRootfsManifest, createRootfsPublicationResult, createRootfsScriptCommand, deriveRootfsVersion, extractRootfsCid, extractRootfsSourceSizeBytes, finalizeRootfsBuildPipeline, parseIpfsAddResponse, parseRootfsContract, parseStoreMessageResponse, parseStoreMessageStatus, publicationArtifacts, publishRootfs, readRootfsContractFile, referenceProfileContractPath, referenceProfileRoot, referenceProfileRootfsDir, resolveRootfsManifestOutputPaths, rootfsBuildShellEnv, rootfsSourceSizeBytesFromIpfsAddResponse, selectRootfsExecutionPlan, serializeRootfsManifest, summarizeStoreMessageFailure, validateRootfsContract };

package/index.js

@@ -0,0 +1,640 @@
+// src/contract.ts
+import { readFile } from "fs/promises";
+import { fileURLToPath } from "url";
+function asObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function asString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function parsePorts(value, errors) {
+  if (!Array.isArray(value)) {
+    errors.push("ports must be an array");
+    return [];
+  }
+  return value.flatMap((entry, index) => {
+    const port = asObject(entry);
+    if (!port) {
+      errors.push(`ports[${index}] must be an object`);
+      return [];
+    }
+    const portNumber = asNumber(port.port);
+    if (portNumber == null || portNumber < 1 || portNumber > 65535) {
+      errors.push(`ports[${index}].port must be an integer between 1 and 65535`);
+      return [];
+    }
+    return [{
+      port: portNumber,
+      tcp: port.tcp === true,
+      udp: port.udp === true,
+      purpose: asString(port.purpose) ?? void 0
+    }];
+  });
+}
+function validateRootfsContract(input) {
+  const errors = [];
+  const payload = asObject(input);
+  if (!payload) {
+    return { contract: null, valid: false, errors: ["rootfs contract must be an object"] };
+  }
+  const rootfs = asObject(payload.rootfs);
+  const services = asObject(payload.services);
+  const manifest = asObject(payload.manifest);
+  const source = asObject(payload.source) ?? void 0;
+  const schemaVersion = asNumber(payload.schemaVersion);
+  if (schemaVersion == null || !Number.isInteger(schemaVersion)) {
+    errors.push("schemaVersion must be an integer");
+  }
+  const id = asString(payload.id);
+  if (!id) {
+    errors.push("id must be a non-empty string");
+  }
+  if (!rootfs) {
+    errors.push("rootfs must be an object");
+  }
+  if (!services) {
+    errors.push("services must be an object");
+  }
+  if (!manifest) {
+    errors.push("manifest must be an object");
+  }
+  const profile = asString(rootfs?.profile);
+  if (!profile) errors.push("rootfs.profile must be a non-empty string");
+  const installMode = asString(rootfs?.installMode);
+  if (!installMode) errors.push("rootfs.installMode must be a non-empty string");
+  const installDir = asString(rootfs?.installDir);
+  if (!installDir) errors.push("rootfs.installDir must be a non-empty string");
+  const binaryPath = asString(rootfs?.binaryPath) ?? "/usr/local/bin/universal-chat-go";
+  const dataDir = asString(rootfs?.dataDir);
+  if (!dataDir) errors.push("rootfs.dataDir must be a non-empty string");
+  const envFile = asString(rootfs?.envFile);
+  if (!envFile) errors.push("rootfs.envFile must be a non-empty string");
+  const bootstrap = asString(services?.bootstrap);
+  if (!bootstrap) errors.push("services.bootstrap must be a non-empty string");
+  const main = asString(services?.main);
+  if (!main) errors.push("services.main must be a non-empty string");
+  const autotlsRefresh = asString(services?.autotlsRefresh);
+  if (!autotlsRefresh) errors.push("services.autotlsRefresh must be a non-empty string");
+  const copyTarget = asString(manifest?.copyTarget);
+  if (!copyTarget) errors.push("manifest.copyTarget must be a non-empty string");
+  const ports = parsePorts(payload.ports, errors);
+  if (errors.length > 0 || !schemaVersion || !id || !profile || !installMode || !installDir || !dataDir || !envFile || !bootstrap || !main || !autotlsRefresh || !copyTarget) {
+    return { contract: null, valid: false, errors };
+  }
+  return {
+    contract: {
+      schemaVersion,
+      id,
+      displayName: asString(payload.displayName) ?? void 0,
+      source: source ? {
+        repository: asString(source.repository) ?? void 0,
+        subdirectory: asString(source.subdirectory) ?? void 0
+      } : void 0,
+      rootfs: { profile, installMode, installDir, binaryPath, dataDir, envFile },
+      services: { bootstrap, main, autotlsRefresh },
+      ports,
+      manifest: { copyTarget, notes: asString(manifest?.notes) ?? void 0 }
+    },
+    valid: true,
+    errors: []
+  };
+}
+function parseRootfsContract(input) {
+  const payload = typeof input === "string" ? JSON.parse(input) : input;
+  const result = validateRootfsContract(payload);
+  if (!result.valid || !result.contract) {
+    throw new Error(`Invalid rootfs contract: ${result.errors.join("; ")}`);
+  }
+  return result.contract;
+}
+async function readRootfsContractFile(path4) {
+  return parseRootfsContract(await readFile(path4, "utf8"));
+}
+function contractShellEnv(contract, contractPath = "") {
+  return {
+    ROOTFS_CONTRACT_PATH: contractPath,
+    ROOTFS_CONTRACT_ID: contract.id,
+    ROOTFS_CONTRACT_PROFILE: contract.rootfs.profile,
+    ROOTFS_CONTRACT_INSTALL_MODE: contract.rootfs.installMode,
+    ROOTFS_CONTRACT_SOURCE_SUBDIRECTORY: contract.source?.subdirectory ?? "",
+    ROOTFS_CONTRACT_INSTALL_DIR: contract.rootfs.installDir,
+    ROOTFS_CONTRACT_BINARY_PATH: contract.rootfs.binaryPath,
+    ROOTFS_CONTRACT_DATA_DIR: contract.rootfs.dataDir,
+    ROOTFS_CONTRACT_ENV_FILE: contract.rootfs.envFile,
+    ROOTFS_CONTRACT_MAIN_SERVICE: contract.services.main,
+    ROOTFS_CONTRACT_BOOTSTRAP_SERVICE: contract.services.bootstrap,
+    ROOTFS_CONTRACT_AUTOTLS_SERVICE: contract.services.autotlsRefresh,
+    ROOTFS_CONTRACT_MANIFEST_COPY_TARGET: contract.manifest.copyTarget,
+    ROOTFS_CONTRACT_MANIFEST_NOTES: contract.manifest.notes ?? "",
+    ROOTFS_CONTRACT_PORT_FORWARDS_JSON: JSON.stringify(contract.ports)
+  };
+}
+function referenceProfileRoot(profile) {
+  return fileURLToPath(new URL(`../reference/${profile}/`, import.meta.url));
+}
+function referenceProfileContractPath(profile) {
+  return fileURLToPath(new URL(`../reference/${profile}/contract.json`, import.meta.url));
+}
+function referenceProfileRootfsDir(profile) {
+  return fileURLToPath(new URL(`../reference/${profile}/rootfs/`, import.meta.url));
+}
+
+// src/build-plan.ts
+import path from "path";
+function positiveInteger(value, fallback) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function deriveRootfsVersion(options = {}) {
+  if (options.rootfsVersion && options.rootfsVersion.trim()) {
+    return options.rootfsVersion.trim();
+  }
+  if (options.gitShortSha && options.gitShortSha.trim()) {
+    const now = options.now ?? /* @__PURE__ */ new Date();
+    const yyyy = String(now.getUTCFullYear());
+    const mm = String(now.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(now.getUTCDate()).padStart(2, "0");
+    return `uc-go-peer-git-${yyyy}${mm}${dd}-${options.gitShortSha.trim()}`;
+  }
+  return "uc-go-peer-v0.1.0";
+}
+function createRootfsBuildPlan(contract, options) {
+  const projectDir = path.resolve(options.projectDir);
+  const alephDir = path.resolve(options.alephDir ?? path.join(projectDir, "go-peer/aleph"));
+  const outDir = path.resolve(options.outDir ?? path.join(alephDir, "dist-rootfs"));
+  const contractPath = path.resolve(options.contractPath ?? path.join(alephDir, "root-profiles", `${contract.id}.json`));
+  const rootfsVersion = deriveRootfsVersion(options);
+  const copyTarget = contract.manifest.copyTarget?.trim() ?? "";
+  const latestManifestPath = copyTarget ? path.resolve(copyTarget.startsWith("/") ? copyTarget : path.join(projectDir, copyTarget)) : null;
+  const versionedManifestPath = latestManifestPath ? path.join(path.dirname(latestManifestPath), `${rootfsVersion}.json`) : null;
+  return {
+    contract,
+    contractPath,
+    projectDir,
+    alephDir,
+    outDir,
+    driver: options.driver ?? "auto",
+    rootfsSizeMiB: positiveInteger(options.rootfsSizeMiB, 20480),
+    rootfsImageSize: options.rootfsImageSize?.trim() || "20G",
+    rootfsVersion,
+    channel: options.channel?.trim() || "ALEPH-CLOUDSOLUTIONS",
+    skipUpload: options.skipUpload === true,
+    skipBuild: options.skipBuild === true,
+    ipfsAddUrl: options.ipfsAddUrl?.trim() || "https://ipfs.aleph.cloud/api/v0/add",
+    ipfsGatewayUrl: options.ipfsGatewayUrl?.trim() || "https://ipfs.aleph.cloud/ipfs",
+    alephApiHost: options.alephApiHost?.trim() || "https://api2.aleph.im",
+    alephMessageWaitAttempts: positiveInteger(options.alephMessageWaitAttempts, 60),
+    alephMessageWaitDelaySeconds: positiveInteger(options.alephMessageWaitDelaySeconds, 5),
+    alephPinAttempts: positiveInteger(options.alephPinAttempts, 4),
+    alephPinDelaySeconds: positiveInteger(options.alephPinDelaySeconds, 10),
+    ipfsGatewayWaitAttempts: positiveInteger(options.ipfsGatewayWaitAttempts, 30),
+    ipfsGatewayWaitDelaySeconds: positiveInteger(options.ipfsGatewayWaitDelaySeconds, 10),
+    manifestPath: path.join(outDir, "rootfs-manifest.json"),
+    latestManifestPath,
+    versionedManifestPath,
+    imagePath: path.join(outDir, "aleph-uc-go-peer.qcow2"),
+    baseImagePath: path.join(outDir, "debian-12-genericcloud-amd64.qcow2"),
+    binaryPath: path.join(outDir, "universal-chat-go")
+  };
+}
+function rootfsBuildShellEnv(plan) {
+  return {
+    OUT_DIR: plan.outDir,
+    ROOTFS_CONTRACT_FILE: plan.contractPath,
+    ROOTFS_BUILD_DRIVER: plan.driver,
+    ROOTFS_SIZE_MIB: String(plan.rootfsSizeMiB),
+    ROOTFS_IMAGE_SIZE: plan.rootfsImageSize,
+    ROOTFS_VERSION: plan.rootfsVersion,
+    CHANNEL: plan.channel,
+    SKIP_UPLOAD: plan.skipUpload ? "1" : "0",
+    SKIP_BUILD: plan.skipBuild ? "1" : "0",
+    IPFS_ADD_URL: plan.ipfsAddUrl,
+    IPFS_GATEWAY_URL: plan.ipfsGatewayUrl,
+    ALEPH_API_HOST: plan.alephApiHost,
+    ALEPH_MESSAGE_WAIT_ATTEMPTS: String(plan.alephMessageWaitAttempts),
+    ALEPH_MESSAGE_WAIT_DELAY_SECONDS: String(plan.alephMessageWaitDelaySeconds),
+    ALEPH_PIN_ATTEMPTS: String(plan.alephPinAttempts),
+    ALEPH_PIN_DELAY_SECONDS: String(plan.alephPinDelaySeconds),
+    IPFS_GATEWAY_WAIT_ATTEMPTS: String(plan.ipfsGatewayWaitAttempts),
+    IPFS_GATEWAY_WAIT_DELAY_SECONDS: String(plan.ipfsGatewayWaitDelaySeconds)
+  };
+}
+
+// src/manifest.ts
+import { dirname, extname, isAbsolute, join } from "path";
+function rootfsSourceSizeBytesFromIpfsAddResponse(content) {
+  const lines = content.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean);
+  if (lines.length === 0) {
+    return void 0;
+  }
+  const payload = JSON.parse(lines.at(-1) ?? "{}");
+  const size = payload.Size;
+  if (typeof size === "number" && Number.isFinite(size) && size > 0) {
+    return size;
+  }
+  if (typeof size === "string" && /^\d+$/u.test(size)) {
+    return Number(size);
+  }
+  return void 0;
+}
+function createRootfsManifest(plan, contract, options = {}) {
+  const manifest = {
+    profile: contract.rootfs.profile,
+    version: plan.rootfsVersion,
+    rootfsInstallStrategy: contract.rootfs.installMode,
+    requiresBootstrapNetwork: false,
+    bootstrapSummary: "Dependencies are preinstalled in the image.",
+    requiredPortForwards: contract.ports,
+    rootfsSizeMiB: plan.rootfsSizeMiB,
+    createdAt: options.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    notes: contract.manifest.notes ?? ""
+  };
+  if (typeof options.rootfsSourceSizeBytes === "number" && Number.isFinite(options.rootfsSourceSizeBytes) && options.rootfsSourceSizeBytes > 0) {
+    manifest.rootfsSourceSizeBytes = options.rootfsSourceSizeBytes;
+  }
+  if (options.rootfsCid) {
+    manifest.rootfsCid = options.rootfsCid;
+  }
+  if (options.rootfsItemHash) {
+    manifest.rootfsItemHash = options.rootfsItemHash;
+  }
+  return manifest;
+}
+function resolveRootfsManifestOutputPaths(plan) {
+  const paths = {
+    primaryPath: plan.manifestPath
+  };
+  const copyTarget = plan.latestManifestPath;
+  if (!copyTarget) {
+    return paths;
+  }
+  const resolvedCopyTarget = isAbsolute(copyTarget) ? copyTarget : join(plan.projectDir, copyTarget);
+  paths.copyTargetPath = resolvedCopyTarget;
+  const copyTargetExt = extname(resolvedCopyTarget) || ".json";
+  paths.versionedTargetPath = join(dirname(resolvedCopyTarget), `${plan.rootfsVersion}${copyTargetExt}`);
+  return paths;
+}
+function serializeRootfsManifest(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}
+`;
+}
+
+// src/execution-plan.ts
+import path2 from "path";
+function ensurePathWithin(parent, child, label) {
+  const relative = path2.relative(parent, child);
+  if (relative.startsWith("..") || path2.isAbsolute(relative)) {
+    throw new Error(`${label} must be inside ${parent}`);
+  }
+  return relative || ".";
+}
+function containerPathForProjectFile(hostPath, projectDir, mountPath, label) {
+  const relative = ensurePathWithin(projectDir, hostPath, label);
+  return path2.posix.join(mountPath, relative.split(path2.sep).join("/"));
+}
+function resolveReferenceRootfsDir(contract, override) {
+  if (override) {
+    return path2.resolve(override);
+  }
+  return referenceProfileRootfsDir(contract.id);
+}
+function createHostRootfsExecutionPlan(plan, options = {}) {
+  const referenceRootfsDir = resolveReferenceRootfsDir(plan.contract, options.referenceRootfsDir);
+  return {
+    mode: "host",
+    reason: "Using host virt-customize/qemu-img toolchain.",
+    referenceRootfsDir,
+    runCommand: {
+      command: "bash",
+      args: [path2.join(referenceRootfsDir, "build-rootfs-image.sh")],
+      workdir: referenceRootfsDir,
+      env: {
+        PROJECT_DIR: plan.projectDir,
+        OUT_DIR: plan.outDir,
+        ROOTFS_CONTRACT_FILE: plan.contractPath,
+        ROOTFS_IMAGE_SIZE: plan.rootfsImageSize
+      }
+    }
+  };
+}
+function createDockerRootfsExecutionPlan(plan, options = {}) {
+  const referenceRootfsDir = resolveReferenceRootfsDir(plan.contract, options.referenceRootfsDir);
+  const projectMountPath = options.projectMountPath ?? "/workspace/project";
+  const rootfsMountPath = options.rootfsMountPath ?? "/workspace/shared-rootfs";
+  const dockerImageTag = options.dockerImageTag ?? `${plan.contract.id}-rootfs-builder:local`;
+  const containerProjectDir = projectMountPath;
+  const containerContractPath = containerPathForProjectFile(plan.contractPath, plan.projectDir, projectMountPath, "contractPath");
+  const containerOutDir = containerPathForProjectFile(plan.outDir, plan.projectDir, projectMountPath, "outDir");
+  return {
+    mode: "docker",
+    reason: "Using Dockerized Debian/libguestfs builder.",
+    referenceRootfsDir,
+    prepareCommand: {
+      command: "docker",
+      args: [
+        "build",
+        "--platform",
+        "linux/amd64",
+        "-t",
+        dockerImageTag,
+        "-f",
+        path2.join(referenceRootfsDir, "Dockerfile.rootfs"),
+        referenceRootfsDir
+      ]
+    },
+    runCommand: {
+      command: "docker",
+      args: [
+        "run",
+        "--rm",
+        "--privileged",
+        "--platform",
+        "linux/amd64",
+        "-e",
+        "LIBGUESTFS_BACKEND=direct",
+        "-e",
+        `ROOTFS_CONTRACT_FILE=${containerContractPath}`,
+        "-e",
+        `OUT_DIR=${containerOutDir}`,
+        "-e",
+        `ROOTFS_IMAGE_SIZE=${plan.rootfsImageSize}`,
+        "-e",
+        `PROJECT_DIR=${containerProjectDir}`,
+        "-v",
+        `${plan.projectDir}:${projectMountPath}`,
+        "-v",
+        `${referenceRootfsDir}:${rootfsMountPath}`,
+        "-w",
+        rootfsMountPath,
+        dockerImageTag,
+        "bash",
+        path2.posix.join(rootfsMountPath, "build-rootfs-image.sh")
+      ]
+    }
+  };
+}
+function selectRootfsExecutionPlan(plan, availability, options = {}) {
+  if (plan.driver === "host") {
+    if (!availability.hasVirtCustomize) {
+      throw new Error("ROOTFS_BUILD_DRIVER=host requested, but virt-customize is not available.");
+    }
+    return createHostRootfsExecutionPlan(plan, options);
+  }
+  if (plan.driver === "docker") {
+    if (!availability.hasDocker) {
+      throw new Error("ROOTFS_BUILD_DRIVER=docker requested, but docker is not available.");
+    }
+    if (availability.dockerDaemonRunning === false) {
+      throw new Error("ROOTFS_BUILD_DRIVER=docker requested, but the Docker daemon is not running.");
+    }
+    return createDockerRootfsExecutionPlan(plan, options);
+  }
+  if (availability.githubActions && availability.hasDocker && availability.dockerDaemonRunning !== false) {
+    return createDockerRootfsExecutionPlan(plan, options);
+  }
+  if (availability.hasVirtCustomize) {
+    return createHostRootfsExecutionPlan(plan, options);
+  }
+  if (availability.hasDocker && availability.dockerDaemonRunning !== false) {
+    return createDockerRootfsExecutionPlan(plan, options);
+  }
+  throw new Error("No supported rootfs build toolchain is available.");
+}
+
+// src/publication.ts
+import { join as join2 } from "path";
+function publicationArtifacts(plan) {
+  return {
+    ipfsAddResponsePath: join2(plan.outDir, "ipfs-add-response.jsonl"),
+    storeMessagePath: join2(plan.outDir, "store-message.json"),
+    storeMessageStderrPath: join2(plan.outDir, "store-message.stderr.log")
+  };
+}
+function parseIpfsAddResponse(content) {
+  return content.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean).map((line) => JSON.parse(line));
+}
+function extractRootfsCid(entries) {
+  if (entries.length === 0) {
+    throw new Error("No response received from the IPFS add endpoint");
+  }
+  const cid = entries.at(-1)?.Hash?.trim();
+  if (!cid) {
+    throw new Error(`IPFS add response did not include a Hash: ${JSON.stringify(entries.at(-1) ?? {})}`);
+  }
+  return cid;
+}
+function extractRootfsSourceSizeBytes(entries) {
+  const size = entries.at(-1)?.Size;
+  if (typeof size === "number" && Number.isFinite(size) && size > 0) {
+    return size;
+  }
+  if (typeof size === "string" && /^\d+$/u.test(size)) {
+    return Number(size);
+  }
+  return void 0;
+}
+function parseStoreMessageResponse(content) {
+  const payload = JSON.parse(content);
+  const itemHash = payload.item_hash?.trim();
+  if (!itemHash) {
+    throw new Error("Failed to extract Aleph item hash from store message response");
+  }
+  return { item_hash: itemHash };
+}
+function summarizeStoreMessageFailure(stderrContent) {
+  return stderrContent.trim() || "Aleph pin failed without stderr output";
+}
+function parseStoreMessageStatus(content) {
+  const payload = JSON.parse(content);
+  const status = payload.status?.trim() ?? "";
+  if (status !== "rejected") {
+    return { status };
+  }
+  const firstError = Array.isArray(payload.details?.errors) ? payload.details.errors[0] : void 0;
+  if (payload.error_code === 5 && firstError && firstError.account_balance != null && firstError.required_balance != null) {
+    return {
+      status,
+      rejectionSummary: `insufficient Aleph balance: account has ${firstError.account_balance}, required is ${firstError.required_balance}`
+    };
+  }
+  if (payload.error_code == null) {
+    return {
+      status,
+      rejectionSummary: JSON.stringify(payload.details ?? {})
+    };
+  }
+  return {
+    status,
+    rejectionSummary: `error ${payload.error_code}: ${JSON.stringify(payload.details ?? {})}`
+  };
+}
+function createRootfsPublicationResult(ipfsAddContent, storeMessageContent) {
+  const entries = parseIpfsAddResponse(ipfsAddContent);
+  const storeMessage = parseStoreMessageResponse(storeMessageContent);
+  return {
+    cid: extractRootfsCid(entries),
+    itemHash: storeMessage.item_hash,
+    sourceSizeBytes: extractRootfsSourceSizeBytes(entries)
+  };
+}
+
+// src/orchestration.ts
+function createRootfsBuildPipeline(buildPlan, availability, options = {}) {
+  return {
+    buildPlan,
+    executionPlan: selectRootfsExecutionPlan(buildPlan, availability, options),
+    publicationArtifacts: publicationArtifacts(buildPlan),
+    manifestPaths: resolveRootfsManifestOutputPaths(buildPlan)
+  };
+}
+function createHostRootfsBuildPipeline(buildPlan, options = {}) {
+  return {
+    buildPlan,
+    executionPlan: createHostRootfsExecutionPlan(buildPlan, options),
+    publicationArtifacts: publicationArtifacts(buildPlan),
+    manifestPaths: resolveRootfsManifestOutputPaths(buildPlan)
+  };
+}
+function createDockerRootfsBuildPipeline(buildPlan, options = {}) {
+  return {
+    buildPlan,
+    executionPlan: createDockerRootfsExecutionPlan(buildPlan, options),
+    publicationArtifacts: publicationArtifacts(buildPlan),
+    manifestPaths: resolveRootfsManifestOutputPaths(buildPlan)
+  };
+}
+function finalizeRootfsBuildPipeline(buildPlan, options = {}) {
+  let publication;
+  if (options.ipfsAddResponseContent && options.storeMessageContent) {
+    publication = createRootfsPublicationResult(options.ipfsAddResponseContent, options.storeMessageContent);
+  }
+  const manifest = createRootfsManifest(buildPlan, buildPlan.contract, {
+    createdAt: options.createdAt,
+    rootfsCid: publication?.cid ?? options.rootfsCid,
+    rootfsItemHash: publication?.itemHash ?? options.rootfsItemHash,
+    rootfsSourceSizeBytes: publication?.sourceSizeBytes ?? options.rootfsSourceSizeBytes
+  });
+  return {
+    manifest,
+    manifestJson: serializeRootfsManifest(manifest),
+    manifestPaths: resolveRootfsManifestOutputPaths(buildPlan),
+    publication
+  };
+}
+
+// src/executor.ts
+import path3 from "path";
+function rootfsScriptDir(buildPlan, override) {
+  return override ? path3.resolve(override) : referenceProfileRootfsDir(buildPlan.contract.id);
+}
+function createRootfsScriptCommand(buildPlan, referenceRootfsDir) {
+  const scriptDir = rootfsScriptDir(buildPlan, referenceRootfsDir);
+  return {
+    command: "bash",
+    args: [path3.join(scriptDir, "build-rootfs.sh")],
+    workdir: scriptDir,
+    env: rootfsBuildShellEnv(buildPlan)
+  };
+}
+async function buildRootfs(buildPlan, deps, availability, options = {}) {
+  const pipeline = createRootfsBuildPipeline(buildPlan, availability, options);
+  const executedCommands = [];
+  if (pipeline.executionPlan.prepareCommand) {
+    const prepareCommand = {
+      command: pipeline.executionPlan.prepareCommand.command,
+      args: pipeline.executionPlan.prepareCommand.args,
+      workdir: pipeline.executionPlan.prepareCommand.workdir,
+      env: pipeline.executionPlan.prepareCommand.env
+    };
+    await deps.run(prepareCommand);
+    executedCommands.push(prepareCommand);
+  }
+  const runCommand = {
+    command: pipeline.executionPlan.runCommand.command,
+    args: pipeline.executionPlan.runCommand.args,
+    workdir: pipeline.executionPlan.runCommand.workdir,
+    env: pipeline.executionPlan.runCommand.env
+  };
+  await deps.run(runCommand);
+  executedCommands.push(runCommand);
+  return {
+    pipeline,
+    executedCommands
+  };
+}
+async function publishRootfs(buildPlan, deps, options = {}) {
+  const command = createRootfsScriptCommand(buildPlan, options.referenceRootfsDir);
+  await deps.run(command);
+  let ipfsAddResponseContent;
+  let storeMessageContent;
+  const publicationArtifacts2 = {
+    ipfsAddResponsePath: path3.join(buildPlan.outDir, "ipfs-add-response.jsonl"),
+    storeMessagePath: path3.join(buildPlan.outDir, "store-message.json"),
+    storeMessageStderrPath: path3.join(buildPlan.outDir, "store-message.stderr.log")
+  };
+  if (!buildPlan.skipUpload) {
+    ipfsAddResponseContent = await deps.readText(publicationArtifacts2.ipfsAddResponsePath);
+    storeMessageContent = await deps.readText(publicationArtifacts2.storeMessagePath);
+  }
+  const finalized = finalizeRootfsBuildPipeline(buildPlan, {
+    createdAt: options.createdAt,
+    ipfsAddResponseContent,
+    storeMessageContent
+  });
+  return {
+    pipeline: {
+      buildPlan,
+      executionPlan: {
+        mode: "docker",
+        reason: "Running shared rootfs build orchestrator script.",
+        referenceRootfsDir: command.workdir ?? rootfsScriptDir(buildPlan, options.referenceRootfsDir),
+        runCommand: {
+          command: command.command,
+          args: command.args,
+          workdir: command.workdir,
+          env: command.env
+        }
+      },
+      publicationArtifacts: publicationArtifacts2,
+      manifestPaths: finalized.manifestPaths
+    },
+    executedCommands: [command],
+    finalized
+  };
+}
+export {
+  buildRootfs,
+  contractShellEnv,
+  createDockerRootfsBuildPipeline,
+  createDockerRootfsExecutionPlan,
+  createHostRootfsBuildPipeline,
+  createHostRootfsExecutionPlan,
+  createRootfsBuildPipeline,
+  createRootfsBuildPlan,
+  createRootfsManifest,
+  createRootfsPublicationResult,
+  createRootfsScriptCommand,
+  deriveRootfsVersion,
+  extractRootfsCid,
+  extractRootfsSourceSizeBytes,
+  finalizeRootfsBuildPipeline,
+  parseIpfsAddResponse,
+  parseRootfsContract,
+  parseStoreMessageResponse,
+  parseStoreMessageStatus,
+  publicationArtifacts,
+  publishRootfs,
+  readRootfsContractFile,
+  referenceProfileContractPath,
+  referenceProfileRoot,
+  referenceProfileRootfsDir,
+  resolveRootfsManifestOutputPaths,
+  rootfsBuildShellEnv,
+  rootfsSourceSizeBytesFromIpfsAddResponse,
+  selectRootfsExecutionPlan,
+  serializeRootfsManifest,
+  summarizeStoreMessageFailure,
+  validateRootfsContract
+};

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@le-space/rootfs",
+  "version": "0.1.3",
+  "description": "Shared rootfs contract parsing, reference profile assets, and build helpers.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}