Dohballs: Folder-Based Code Sharing

A Dohball is an automated snapshot of a folder's contents, where that folder acts as a container for one or more Doh Packages or Modules. These snapshots are versioned using Doh's internal dohver.js incremental versioning system.

The primary purpose of Dohballs is to provide a "management-less" way for a developer's Doh projects to act as internal repositories for each other.

This system excels at facilitating the seamless sharing, linear updating, and organic evolution of:

• A foundational internal toolkit: your personal or team's collection of essential utilities, base Doh patterns (like DohPath), and custom modules.
• Project-specific components that need to be shared across different parts of a larger Doh application or between closely related instances.

Think of Dohballs not as a replacement for NPM (for public libraries) or Git (for comprehensive source control), but as a specialized, complementary tool. They are particularly powerful for:

• Cultivating your evolving internal component library. Let them grow from simple helpers into distinct modules, splitting and refactoring "like cells" as your needs dictate, without the typical packaging overhead for each internal iteration.
• Ensuring consistency and easily propagating updates of your core utilities and architectural patterns across all your Doh projects.
• Gracefully upgrading revisited projects with your latest foundational code.

Dohballs are designed for largely transparent operation, automated by the Auto-Packager and the dohball_host module. They are distinct from real-time file synchronization systems; Dohballs provide a more deliberate, version-incremented way to update shared codebases. In essence, a Dohball is more akin to a versioned "fork" of a shared code segment than a traditional package version. Future enhancements may even allow "melding" these forks.

Important Distinction: Dohballs come in two forms:

• Local Dohballs: Code in your own project that's automatically handled by the Auto-Packager - no installation needed
• Remote Dohballs: Code from other Doh instances that you install via doh install from configured hosts

The "Why": Simplifying Your Internal Code Lifecycle

Dohballs address the desire to manage an internal suite of shared code with maximum flexibility and minimal administrative burden:

• Frictionless Tool Evolution: Your internal tools can mature without needing to publish a formal package at each step.
• Eliminating Repetitive Setup: Avoids manual copying of shared code or complex sub-module configurations.
• Reduced Management Overhead: No need to maintain individual manifests for every small shared utility for internal use. The Auto-Packager handles this project-wide.
• Streamlined Updates: Consuming projects can update to your latest "good code" with a simple doh upgrade.

Dohballs Support Multiple Distribution Methods

Dohballs can be distributed and shared through two complementary approaches:

1. Git-Based Distribution (Traditional)

• Git: Remains your fundamental tool for source code history and version control.
• Committing Baked Artifacts for Transport & History:
  • The dohball.json file (containing the dohver.js-managed version) resides in the source folder of the packages being baked. The doh bake command updates this file. Users never edit or create dohball.json files manually; doh bake handles this.
  • The actual baked Dohball .tar.gz files (created in project_root/dohballs/) are also intended to be committed to your Git repository alongside your source code and the updated source dohball.json files. This practice serves two main purposes:
    1. It provides a Git-tracked history of your baked artifacts.
    2. For remote/team sharing, Git acts as the transport mechanism to get these baked artifacts onto the file system of the Doh instance that will host them.

2. HTTP-Based Distribution (Direct Hosting)

• Direct HTTP/HTTPS serving: The dohball_host module enables Doh instances to serve baked Dohballs directly via HTTP endpoints.
• No Git required for distribution: Consumer projects can install Dohballs directly from running Doh hosts using doh install or doh upgrade commands.
• Real-time availability: Updates are immediately available to consumers once baked and hosted, without waiting for Git commits/pushes/pulls.

Core Concepts - How Dohballs Work

• Folders as Package Containers: A Dohball is a .tar.gz archive of a specific folder's state, containing source files where Doh Packages/Modules are defined.
• Package-Centric Interaction: You always interact with shared code via Doh Package names (e.g., Doh.load('MyCustomUtility')).
• Versioning with dohver.js:
  • The version in a package's source dohball.json is an incremental string like 0.0.1a, managed by dohver.js. This is not a content hash.
  • doh bake uses dohver.js to update this version in the source dohball.json if changes warrant.
  • This indicates a linear progression of updates. Access to specific older versions relies on Git history.
• Minimal Internal Archive Metadata (dohball.json inside the .tar.gz):
  • version: The dohver.js-generated version, copied from the source dohball.json.
  • removals[]: An array of file paths no longer present, for cleanup by the consumer.
• Consumer's Auto-Packager Manages Full Manifests: Detailed manifests are not in the Dohball. The consuming project's Auto-Packager analyzes installed Dohball contents and updates its own local manifests.

Working with Dohballs: Practical Workflows & Configuration

The dohball_host system is networkable. A Doh instance can consume from multiple hosts (via http:// or https:// URLs in pod.yaml's dohball_host list) and can be both a host and a consumer, enabling "lazy push/pull" of code between isolated monorepos or instances.

Fine-Tuning Dohball Contents: The Ignore System

Control what gets included using these pod.yaml settings:

1. Global packager_ignore: Dohballs respect global packager_ignore settings (e.g., for node_modules, .git).
2. Dohball-Specific Ignores (in dohball_deployment section):
   • ignore_paths: List directory paths (relative to project root) never to include in any Dohball, nor whose packages should trigger Dohball creation for that path.
   • ignore_packages: List specific Doh Package names. These packages won't be "exposed," and their containing folders won't be baked on their behalf. (Often, expose_packages: '*' is used, with these ignores providing refinement.)
3. Implicit Exclusion of Nested Dohball Containers: If Folder A (being baked) contains Sub-folder B, and B is itself a root for packages forming their own separate Dohball, B's contents are excluded from A's Dohball.

A. Local Development (No Installation Required)

Goal: Develop and use your own code within your project seamlessly.

How It Works:

1. Simply Add Code: Put your modules, packages, and patterns in your project structure.
2. Auto-Packager Handles Everything: The Auto-Packager automatically:
   • Discovers your code
   • Resolves dependencies
   • Makes everything available for loading
   • Updates when you make changes
3. No Installation Commands Needed: Your local code is immediately runnable without any doh install or similar commands.

Example Local Workflow:

# You create a new module
mkdir -p modules/my_feature
# Add your code to modules/my_feature/my_module.js

# Auto-Packager automatically makes it available
# You can immediately use it: Doh.load('my_module')

# Make changes to your code
# Changes are reflected immediately - no rebuild/install needed

B. Remote Dohball Installation (From External Hosts)

Goal: Install and use code from other Doh instances via remote hosting.

Setup (Consuming Project):

1. Configure Remote Hosts: Add external hosts to pod.yaml:

   dohball_host:
     - https://team-host.com
     - http://localhost:3001
   

Installation Workflow:

1. Install from Remote: Run doh install package_name to pull from configured hosts.
2. Upgrade When Available: Run doh upgrade to get newer versions from hosts.
3. Use Installed Code: Once installed, remote code works just like local code.

Note: This is different from local development - remote dohballs require explicit installation steps.

C. Team Sharing / Remote Host Updates

Dohballs support two approaches for team sharing:

C1. Git-Mediated Artifact Transport (Traditional)

Goal: Use Git to transport baked Dohball artifacts to a shared Doh instance (e.g., team server), which then acts as the dohball_host for other consumers. This facilitates team management of a shared component library where "build artifacts" become installable.

Steps (Sharer/Developer - On Local Machine):

1. Develop & Bake: Make code changes, run doh bake.
   • What this does: Updates source dohball.json versions and refreshes .tar.gz files in /dohballs/.
2. Commit & Push Artifacts to Git: Commit source code, updated source dohball.json files, and the /dohballs/ directory. Push to your remote Git repo.
   • What this does: Git now holds the specific "build artifacts" (Dohballs and their versioned source dohball.jsons), ready for the hosting instance.

Steps (Remote Hosting Instance - e.g., Central Team Server):

1. Pull Artifacts from Git: On the server, git pull.
   • What this does: Updates the server's local file system with the new .tar.gz files in its /dohballs/ and the source dohball.json files.
2. Reboot Service: Restart the Doh application on this host (e.g., doh pm2 restart).
   • What this does: The host (running dohball_host module with compile_manifest: true) regenerates its public manifest, reflecting the now-updated Dohballs it can serve.

Steps (Consuming Instance - Team Member's Project, CI, etc.):

1. Configure Host: Ensure its pod.yaml lists the remote host.
2. Upgrade Consumer: Run doh upgrade.
   • What this does: Fetches the host's updated public manifest, compares dohver.js versions, and doh installs newer Dohballs.
3. Reboot (if needed): Restart its Doh application.

C2. Direct HTTP Hosting

Goal: Serve Dohballs directly via HTTP/HTTPS without requiring Git transport, enabling real-time distribution of updates.

Setup (Hosting Instance):

1. Configure the Host: Set up pod.yaml with:

   dohball_deployment:
     compile_manifest: true
   host_load:
     - dohball_host  # Enable the dohball_host module
   

2. Bake and Host: Run doh bake to create Dohballs, then doh run to start serving them.

Setup (Consuming Instance):

1. Configure Consumer: Add the host to pod.yaml:

   dohball_host:
     - https://your-host.com
     - http://localhost:3001  # For local development
   

2. Install/Update: Use doh install package_name or doh upgrade to fetch directly from the host.

Benefits of Direct HTTP Hosting:

• No Git dependency: Consumers don't need to pull Git repositories
• Real-time updates: Changes are available immediately after baking
• Simplified workflow: No need to commit/push/pull baked artifacts
• Better for CI/CD: Automated builds can serve directly to testing/production

6. FAQ

7. Design Philosophy Recap

Source remains sacred; builds remain ephemeral artifacts. Dohballs embody this by snapshotting folders as-is and letting every consuming Doh instance re-interpret their contents through its own Auto-Packager. The dohver.js system provides a simple, linear way to track updates. You trade the complexity of semantic versioning and manual publishing for teleport-grade portability and the freedom to organically evolve hundreds of interconnected components within your own Doh ecosystem.

Happy baking—and even happier not thinking about it most of the time!