packages

The packages project is the open-source package monorepo for moldea. It develops the first-class public and private packages, shared internal packages, compatibility data, conformance fixtures, and generation tooling that implement the deterministic repository-reading and repository-format ecosystem.

The repository is intentionally separate from the hosted platform monorepo. It contains reusable package products and their shared development infrastructure, not Cloud applications, hosted APIs, runtime infrastructure, or deployment configuration.

@moldea.ai/repository, @moldea.ai/repository-fs, @moldea.ai/core, @moldea.ai/adapter-openai, and @moldea.ai/cli form the first available package set. Repository and Core provide the source-neutral reader and universal interpretation foundations, Repository FS supplies the coherent local-filesystem reader, the OpenAI adapter contributes static evidence for its experimental direct Responses API target, and the CLI composes them into the complete version 1 read-only executable. The built-in custom runtime and package-backed openai runtime are verified as available; the remaining package-backed adapters stay planned. Real tarball installation and execution remain the release boundary for every package version.

Specifications

The product and package specifications are currently maintained in the platform repository:

• moldea packages — monorepo organization, package catalog, dependencies, distribution, and shared conventions.
• @moldea.ai/repository — source-neutral repository-reader contract and in-memory reference implementation.
• @moldea.ai/repository-fs — coherent local filesystem reader.
• @moldea.ai/core — deterministic repository-format interpretation and indexing.
• @moldea.ai/cli — read-only Git working-tree composition and executable contract.
• @moldea.ai/adapter-openai — experimental TypeScript OpenAI Responses API inspection target.
• Runtime Adapter Contract — deterministic extension contract for official adapters.
• Runtime Compatibility Matrix — canonical compatibility-data contract and initial adapter inventory.

The specification documents remain the design authority. Compatibility artifacts are introduced in their specified implementation phase, after their foundational packages and conformance requirements are in place.

Project structure

.github/
  workflows/                   # Repository verification and npm publication
compatibility/
  runtimes.yaml                # Canonical runtime support inventory and claims
configs/
  typescript/                  # Shared environment and declaration configs
  vite/                        # Shared ESM library build configuration
  vitest/                      # Shared package test configuration
fixtures/                      # Repository-wide conformance fixtures
docs/
  npm-releases.md             # Trusted npm publication and bootstrap process
  runtime-compatibility.md     # Generated compatibility presentation
packages/                      # Private shared implementation packages
projects/
  adapter-openai/              # OpenAI Responses API runtime adapter
  cli/                         # Read-only local command-line composition
  core/                        # Deterministic repository-format interpretation
  repository/                  # Source-neutral reader contract and memory reader
  repository-fs/               # Explicit local-filesystem repository reader
scripts/
  runtime-compatibility/       # Matrix validation and deterministic generation
eslint.config.js
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
tsconfig.json
turbo.json
vitest.config.ts
vitest-integration.config.ts

Every immediate child of projects/ is an independently meaningful first-class package. Every immediate child of packages/ is a private shared implementation package. Repository-wide fixtures and other non-package assets remain outside both workspace layers.

Dependency architecture

An arrow means that the package on the left depends on the package on the right.

repository-fs       → repository
repository-github   → repository
core                → repository
adapter-*           → core
cli                 → repository + repository-fs + core + active adapter packages

Shared internal packages may support first-class projects but never depend on them. Published packages must bundle private internal implementation or otherwise ensure that private imports and declarations do not leak into the consumer artifact.

Package catalog

Project	Package	Distribution
repository	@moldea.ai/repository	Public
repository-fs	@moldea.ai/repository-fs	Public
repository-github	@moldea.ai/repository-github	Private initially
core	@moldea.ai/core	Public
cli	@moldea.ai/cli	Public
adapter-anthropic	@moldea.ai/adapter-anthropic	Public
adapter-claude-agent-sdk	@moldea.ai/adapter-claude-agent-sdk	Public
adapter-cloudflare-agents	@moldea.ai/adapter-cloudflare-agents	Public
adapter-eve	@moldea.ai/adapter-eve	Public
adapter-google-genai	@moldea.ai/adapter-google-genai	Public
adapter-langchain	@moldea.ai/adapter-langchain	Public
adapter-langgraph	@moldea.ai/adapter-langgraph	Public
adapter-openai	@moldea.ai/adapter-openai	Public
adapter-openai-agents-sdk	@moldea.ai/adapter-openai-agents-sdk	Public
adapter-pydantic-ai	@moldea.ai/adapter-pydantic-ai	Public
adapter-vercel-ai-sdk	@moldea.ai/adapter-vercel-ai-sdk	Public

The catalog records approved architecture, not implementation or release status. The custom adapter remains built into @moldea.ai/core and has no separate package project.

Requirements

• Node.js 24.15.0 or newer within Node.js 24 for repository development
• pnpm 11.9.0

Development-tool requirements are intentionally separate from consumer runtime guarantees. Node-specific version 1 packages declare and verify the runtime ranges defined by their focused specifications. Environment-neutral packages must not import Node.js modules or inherit Node globals.

Getting started

Install the pinned workspace dependencies:

pnpm install

Run the complete repository verification workflow:

pnpm format:check
pnpm lint
pnpm typecheck
pnpm build
pnpm test

Useful focused commands:

Command	Purpose
pnpm test:root	Run root unit and integration tests.
pnpm test:unit	Run root and package unit-test tasks.
pnpm test:integration	Run root and package integration-test tasks.
pnpm test:e2e	Build and run installed-package end-to-end test tasks.
pnpm format	Format repository-maintained files.
pnpm compatibility:generate	Regenerate compatibility documentation and bundled CLI release metadata.
pnpm compatibility:check	Verify matrix, package, and generated-artifact synchronization.

Build and test conventions

Public JavaScript artifacts are ESM-only unless a focused specification establishes another format. Vite bundles JavaScript in library mode with explicit entry points, stable output names, source maps, and deliberate dependency externalization. TypeScript performs strict source checking and emits declarations separately so public types remain a first-class package artifact. Package build scripts clean their output directory once, run Vite, and then emit declarations; the shared Vite configuration does not delete output owned by another build step.

Environment-neutral packages extend configs/typescript/environment-neutral.json; Node-specific packages extend configs/typescript/node.json. Declaration builds use the corresponding *-library.json configuration and set package-local rootDir and outDir values.

Package tests use Vitest without global test APIs. Tests are colocated with the source modules they exercise, and Node and non-React tests use the *.test-unit.ts, *.test-integration.ts, and *.test-e2e.ts names for the categories they own. Each package exposes a granular script for every category it contains, and its test command runs unit, integration, then end-to-end correctness suites when present. Shared conformance fixtures live at repository level when they represent a contract implemented by multiple packages.

Repository FS, the OpenAI adapter, and CLI runtime compatibility are tested at packed-consumer boundaries. CI builds the required public tarballs on the pinned development runtime, then installs and executes the artifacts with package scripts disabled and strict engine validation on Node.js 22.11.0, latest Node.js 22, Node.js 24.11.0, and latest Node.js 24. The adapter harness exercises the installed public export and inspection boundary, while the CLI harness verifies installed package identities and real version, compatibility, validate, and inspect commands through the packed composition. This keeps consumer runtime guarantees independent from the newer runtime required by repository development tooling.

Turborepo derives build order from declared workspace dependencies. Package dependencies must remain explicit and acyclic, and no task may rely on workspace enumeration order or undeclared cross-project state.

Generated artifacts

Generated files are not edited directly. Runtime compatibility changes begin in compatibility/runtimes.yaml, while exact bundled versions come from the first-class project manifests. Run pnpm compatibility:generate to update docs/runtime-compatibility.md and the CLI's generated immutable release-metadata module. CI runs pnpm compatibility:check and fails when the matrix, package composition, documentation, or bundled metadata is invalid or stale.

Package releases

A push to main automatically selects every changed public project. An existing project must declare a stable version strictly greater than its version at the preceding commit, while a newly introduced project with no base manifest must declare a canonical stable version. The npm workflow verifies the complete release candidate once, then creates package-qualified immutable tags and publishes the exact checksummed tarballs in dependency order through trusted publishing. A project whose version is invalid for its release state fails before publication. Manual dispatch remains available for new-package bootstrap and release recovery. See docs/npm-releases.md.

Initial implementation sequence

The first implementation project was @moldea.ai/repository, followed by its in-memory reader and shared conformance suite. Core's universal behavior was then completed through that memory-reader boundary, followed by Repository FS, the CLI's installed-tarball runtime boundary, and the first official package-backed adapter. The OpenAI adapter now owns an experimental TypeScript Responses API target with deterministic fixtures, diagnostics, evidence, package metadata, and packed-runtime verification. Package publication remains an explicit independently versioned release operation; other official package-backed adapters stay planned until their implementations and fixtures support verified compatibility claims.