IbGib Monorepo

The central repository for the IbGib ecosystem: a framework for creating agentic apps with isomorphic crypto hashing, DLT substrates, and browser-based IndexedDB storage built on the innovative ibgib protocol.

⚡ Quick Start

[!TIP] 🚀 Building Applications with ibgib: Looking to build a downstream application, browser extension, or service on ibgib? Start with the Creating IbGib Applications Guide for a complete architectural map, topology selection, and step-by-step guides for Client and Server development.

The IbGib monorepo is organized into specialized projects. For a complete list of terminal commands for building, testing, and publishing, see the 🛠️ Command Guide.

📁 Project Directory

| Project | Type | Description | | :--- | :--- | :--- | | monorepo | Meta | High-level record of monorepo state, policy, and configuration. | | blank-gib | App | Currently the ibgib.com website, working as a reference implementation/template for ibgib apps. | | helper-gib | Lib | Low-level utilities, logging, and base helper functions. All non-ibgib specific code. | | ts-gib | Lib | Core TypeScript patterns and type-safe utilities. | | encrypt-gib | Lib | Encryption primitives with novel encrypt-gib encryption algorithm. | | core-gib | Lib | The primary ibgib engine, graph logic, and sync protocol built on top of ts-gib. | | web-gib | Lib | Web-specific framework, UI components, app-bootstrap engine, and agent skills. | | node-gib | Lib | Node.js-specific witnesses, filesystem spaces, serve-gib microframework, and AWS email infrastructure. | | build-gib | Engine | The centralized build and publishing orchestration system. |

📦 The Monorepo Package (@ibgib/monorepo)

The @ibgib/monorepo project itself is packageable as a high-level record of the monorepo's state, configuration, and documentation. While it does not contain the source code of the applications or libraries (which are published as independent packages), it preserves the foundational structure and shared policies that bind the ecosystem together.

• Purpose: Acts as a centralized source for monorepo-wide configuration (TSConfig bases, documentation, style guides).
• Structure: Includes root-level documentation, build orchestration metadata, and the empty directory structure for apps/, libs/, and build/ (each containing a descriptive README.md).

⛓️ Chain Orchestration (Local CI/CD)

The monorepo includes powerful "Chain" commands that automatically handle multi-layer dependencies. Use these when you make changes to a low-level library (like helper-gib) and want to verify/pack everything that depends on it.

Chain Testing

Run all tests for a library and every library that depends on it in topological order.

• Example: npm run chain:test:helper-gib

Chain Publishing

Bumps versions and packs a library and every library that depends on it.

• Example: npm run chain:publish:helper-gib
• Output: Generates a summary of npm publish commands for the resulting .tgz files.

📊 Codebase Metrics & Diagnostics

Calculates monorepo source code lines of code (LOC), file counts, and TypeScript 7 extended diagnostics across all projects:

• Command: npm run metrics:tsc (or node metrics/tsc/calc-monorepo-tsc-metrics.mjs)
• Output Reports: Each run automatically outputs to console and saves a timestamped markdown report inside metrics/tsc/YYYY-MM-DD_HH-mm-ss.md.

📜 The Golden Rules

To keep the monorepo healthy and building fast, please adhere to these three simple rules:

1. Root-Level devDependencies

Never install TypeScript, esbuild, or Type definitions (@types/*) inside a library or app folder.

• Action: Always run npm install <package> -D from the monorepo root.

2. Adding Regular Dependencies

When a library (/libs) or app (/apps) needs a new runtime dependency (e.g. lodash):

• Action: Use the workspace flag: npm install <package> -w libs/<name>.
• This ensures the dependency is tracked correctly for that specific project while leveraging the monorepo's shared cache.

3. Orchestration Only

Avoid running tsc or esbuild directly from the command line.

• Action: Use the provided npm scripts. These scripts trigger the custom orchestration logic in /build which handles cleaning, assets, and dynamic file generation automatically.

4. Continuous Documentation

Keep CHANGELOG.md files updated as you work.

• Action: Document features, fixes, and meta-changes under the "Working Version" section of the affected project(s) and/or the monorepo root.
• The chain:publish orchestrator will prompt for verification before proceeding.

📖 Related Docs

• 🛠️ Command Guide
• 🚀 Deployment & Infrastructure Guide
• Architecture & Nuances
• Project Style Guide