Text-to-CAD Version History: Centralized Versioning and Release Workflow

Text-to-CAD version history is governed by a single canonical VERSION file at the repository root, which the CI/CD pipeline propagates to all sub-package manifests to guarantee synchronized releases across the modular architecture.

The earthtojake/text-to-cad repository tracks its release lineage through a unique centralized system rather than independent semantic versioning per package. This approach ensures that every skill and package within the packages/ directory shares the exact same version identifier, eliminating dependency conflicts across the CAD generation, URDF export, and viewer components.

The Canonical VERSION File

The definitive version for the entire project lives in a plaintext file at the repository root.

Location and Purpose

According to the source code analysis, the VERSION file serves as the single source of truth for release tags. Unlike monorepos where each package maintains independent version numbers, text-to-cad uses this root-level file to declare the current release for all modules simultaneously.

# Check the current release version

cat VERSION

This file is referenced by the release automation scripts to tag GitHub releases and update downstream manifests.

Release Workflow and Version Propagation

When maintainers cut a new release, the version identifier flows from the root VERSION file into individual package configurations through automated pipelines.

CI/CD Pipeline Mechanics

The .github/workflows/ directory contains automation that reads the root VERSION file and injects that value into every package.json within the packages/ directory. This ensures that cadjs, cadpy, implicitjs, and cadpy_metadata all ship with identical version strings.

# Example structure after version propagation

cat packages/cadjs/package.json | grep version
cat packages/cadpy/package.json | grep version

Package Manifest Synchronization

The propagation touches manifests in:

• packages/cadjs/package.json – JavaScript CAD geometry helpers
• packages/implicitjs/package.json – GLSL-based implicit CAD runtime
• packages/cadpy/package.json – Python utilities for STEP/GLB generation
• packages/cadpy_metadata/package.json – Metadata handling utilities

This guarantees that when users install the library via npx skills install earthtojake/text-to-cad, all underlying dependencies resolve to the same release epoch.

Development Branch Versioning

The develop branch handles pre-release versioning differently from the main release pipeline to facilitate rapid iteration.

Symlink-Based Development Workflow

During active development, the repository uses symlinks to point runtime folders directly to source packages. The script scripts/dev/setup-symlinks.sh establishes this layout, allowing developers to test changes across packages without bumping version numbers or publishing to registries.

While in this symlinked state, the VERSION file still represents the target release version, but the actual code executed comes from the live source directories rather than vendored packages. This ensures that version history remains consistent even when testing unreleased features.

Version Consistency Guarantees

The architecture enforces strict isolation between skills while maintaining unified versioning. Since skills in skills/cad/, skills/urdf/, and skills/gcode/ never import other skills—only packages—the centralized version in the root VERSION file applies to the shared dependency layer that powers all agent capabilities.

This design means that rolling back the Text-to-CAD version history to a specific release point requires only checking out the repository at that tag, as every package and skill will revert to the compatible versions automatically.

Summary

• Single Source of Truth: The root VERSION file contains the canonical release tag for the entire text-to-cad ecosystem.
• Automated Propagation: CI/CD pipelines update all package.json files in packages/ to match the root version during releases.
• Development Symlinks: The develop branch uses scripts/dev/setup-symlinks.sh to test code without altering version manifests.
• Unified Releases: All packages (cadjs, cadpy, implicitjs) share the same version number, preventing dependency drift.

Frequently Asked Questions

Where is the version number stored in Text-to-CAD?

The version number is stored in the VERSION file at the repository root. This file acts as the canonical release tag that the CI/CD system propagates to all sub-packages, ensuring every module in packages/ and every skill in skills/ shares the same version identifier.

How does Text-to-CAD handle version history across multiple packages?

Rather than maintaining independent version histories for each package, text-to-cad uses a centralized approach. The release pipeline reads the root VERSION file and injects that value into package.json files across packages/cadjs/, packages/cadpy/, and other directories, creating a unified version history for the entire project.

What happens to versions when developing on the develop branch?

On the develop branch, developers run scripts/dev/setup-symlinks.sh to create symlinked environments where packages point to live source code. While the root VERSION file remains unchanged during this phase, the actual executed code comes from the development directories, allowing testing of future versions before they are formally tagged.

How can I install a specific version of Text-to-CAD?

Install specific versions using the skills CLI with the repository reference. The version you install will correspond to the value in the VERSION file at that Git ref, ensuring all underlying packages (cadjs, implicitjs, cadpy) are synchronized to that release:

npx skills install earthtojake/text-to-cad@<version-tag>

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}