Add initial core package structure with TypeScript support

[ColemanSWE]

Add @comfy-spaces/core NPM Package

Purpose

This PR introduces @comfy-spaces/core, a reusable NPM package that extracts the containerization functionality from Comfy-Spaces into a standalone library. This enables other projects to programmatically generate Dockerfiles and build Docker images for ComfyUI spaces without requiring the full Comfy-Spaces application.

Scope

This initial release focuses exclusively on containerization:

• Dockerfile generation from ComfyUI space configurations
• Docker image building via the Docker CLI
• Type definitions for space configurations

Future iterations may include additional functionality like space management, workflow exports, or other utilities.

What's Included

Package Structure

• Location: packages/core/
• Package name: @comfy-spaces/core
• Version: 0.1.0
• Build: Dual CJS/ESM output via TypeScript compiler

Exports

Main Entry (@comfy-spaces/core)

Type definitions matching the app's space.json format:

export type { SpaceConfig, SpaceNode, SpaceMetadata };

Container Subpath (@comfy-spaces/core/container)

Containerization functions and types:

export { generateDockerfile, buildImage };
export type { DockerfileOptions, BuildOptions, BuildResult };

Core Features

1. generateDockerfile(config, options?)

   • Generates Dockerfile content from a SpaceConfig
   • Supports CPU and NVIDIA GPU base images
   • Handles ComfyUI cloning (branch/tag/commit)
   • Clones custom nodes with version control
   • Optional ComfyUI-Manager installation
   • Pip dependencies installation
   • Model path configuration via extra_model_paths.yaml
   • Customizable ports and ComfyUI arguments

2. buildImage(config, options?)

   • Wraps Docker CLI for image building
   • Creates temporary build context
   • Writes generated Dockerfile
   • Streams build output via logger callback
   • Returns structured result with image ID
   • Automatic cleanup of temporary files

Testing

• 31 unit tests (22 for generateDockerfile, 9 for buildImage)
• All tests use Vitest
• Build tests use mocked child_process.spawn to avoid requiring Docker
• Generator tests cover all major use cases and edge cases

Documentation

• Comprehensive README at packages/core/README.md
• API documentation with TypeScript types
• Usage examples for both functions
• Installation instructions

Testing Instructions

Prerequisites

cd packages/core
npm install

1. Run Unit Tests

npm test

All 31 tests should pass.

2. Verify Build

npm run build

This compiles TypeScript to both ESM (dist/esm/) and CJS (dist/cjs/) formats with type declarations (dist/types/).

3. Test Dockerfile Generation (No Docker Required)

node integration-test.mjs --cpu
# or
node integration-test.mjs --gpu

This generates and validates a Dockerfile without requiring Docker. Output is written to test-output-Dockerfile for inspection.

4. Test Full Docker Build (Requires Docker)

If you have Docker installed and running:

node integration-test.mjs --build

This will actually build a Docker image to verify end-to-end functionality.

5. Manual Testing

Create a test.mjs file:

import { generateDockerfile } from './dist/esm/container/index.js';

const config = {
  nodes: [],
  dependencies: ['torch>=2.0.0'],
  metadata: {
    visibleName: 'My Space',
    spaceId: 'my-space',
    pythonVersion: '3.11',
    githubUrl: 'https://github.com/comfyanonymous/ComfyUI',
    branch: null,
    commitId: null,
    releaseTag: null,
  },
};

const dockerfile = generateDockerfile(config, {
  gpu: 'nvidia',
  cudaVersion: '12.6',
});

console.log(dockerfile);

Run: node test.mjs

Changes Summary

New Files (17 files, 2,441+ lines)

• packages/core/package.json - Package configuration
• packages/core/README.md - Documentation
• packages/core/.gitignore - Git ignore rules
• packages/core/tsconfig.json - Base TypeScript config
• packages/core/tsconfig.esm.json - ESM build config
• packages/core/tsconfig.cjs.json - CJS build config
• packages/core/vitest.config.ts - Test configuration
• packages/core/postcss.config.mjs - PostCSS config (prevents parent config issues)
• packages/core/src/types.ts - Core type definitions
• packages/core/src/index.ts - Main entry point
• packages/core/src/container/types.ts - Container types
• packages/core/src/container/generator.ts - Dockerfile generation logic
• packages/core/src/container/build.ts - Docker build logic
• packages/core/src/container/index.ts - Container subpath entry
• packages/core/src/container/generator.test.ts - Generator tests (22 tests)
• packages/core/src/container/build.test.ts - Build tests (9 tests)
• packages/core/integration-test.mjs - Manual integration test script

Technical Highlights

• ESM support: All imports use .js extensions for proper ESM module resolution
• Type safety: Full TypeScript support with declaration files
• Dual module format: Both CommonJS and ESM for maximum compatibility
• Tree-shakeable: Exports are structured for optimal tree-shaking
• Zero runtime dependencies: Only uses Node.js built-in modules

Future Work

This package currently handles containerization only. Potential future additions:

• Space lifecycle management utilities
• Workflow import/export functions
• Model management helpers
• ComfyUI API client
• CLI tools for common operations
• Additional base images (AMD GPU, etc.)

Notes

• This package does not change any existing Comfy-Spaces application code
• The package is designed to be published to npm but is currently scoped for internal use
• All types align with the existing space.json format used by the application

[ColemanSWE]

@ashish-aesthisia Added more info, tests, etc! As noted in the description, this doesn't change any functionality in the codebase itself yet, just adds the package (which is not published to NPM either yet). I can also go through and test using this in the app itself if you'd like, but I thought I'd stop and let you review the progress so far first before I continue!

Let me know what you think. 😸

[ColemanSWE]

Howdy! Checking in on this. 😸