@moldea.ai/repository

@moldea.ai/repository

Source-neutral, read-only repository contracts for the moldea ecosystem.

The version 1 package surface provides the complete source-neutral reader contract and immutable in-memory reference implementation. Tarball, consumer-type, and conformance checks remain the release boundary for every published version.

One reader represents one coherent repository snapshot through portable logical paths. The package does not access a filesystem or network, interpret the moldea format, follow symlinks, decode file content, or expose write operations.

Install after release

The registry command below installs a released version. Source and release-candidate verification installs the packed artifact directly.

pnpm add @moldea.ai/repository

Logical paths

Repository paths are root-absolute within a logical snapshot. They are not host-machine paths. Validate arbitrary strings before passing them to a reader:

import { REPOSITORY_ROOT, isRepositoryPath, parseRepositoryPath } from '@moldea.ai/repository';

const manifestPath = parseRepositoryPath('/moldea/moldea.yaml');

isRepositoryPath(manifestPath); // true
REPOSITORY_ROOT; // '/'

Paths use /, preserve exact case and Unicode, and reject empty, dot, control-character, backslash, drive-letter, URL, trailing-separator, and unpaired-surrogate forms. No Unicode normalization or URL decoding is performed.

Reader contract

import type { IRepositoryReader } from '@moldea.ai/repository';
import { parseRepositoryPath } from '@moldea.ai/repository';

const readManifest = async (reader: IRepositoryReader): Promise<Uint8Array> => {
  return reader.readFile(parseRepositoryPath('/moldea/moldea.yaml'));
};

getEntry performs exact lookup, readFile returns caller-owned exact bytes, and listEntries recursively enumerates directory descendants. All operations accept AbortSignal. Enumeration order has no contract meaning.

Operational failures use RepositorySourceException; malformed logical paths use RepositoryPathException. These exception classes extend Exception from error-message-utils, but consumers only need to catch the concrete repository exceptions.

Immutable memory reader

The memory subpath provides the baseline implementation for fixtures and already-fetched content:

import { parseRepositoryPath } from '@moldea.ai/repository';
import { createMemoryRepositoryReader } from '@moldea.ai/repository/memory';

const reader = createMemoryRepositoryReader([
  {
    path: '/moldea/moldea.yaml',
    type: 'file',
    content: 'version: 1\n',
  },
  {
    path: '/empty-directory',
    type: 'directory',
  },
  {
    path: '/link',
    type: 'symlink',
  },
]);

const bytes = await reader.readFile(parseRepositoryPath('/moldea/moldea.yaml'));

The reader copies input buffers, synthesizes missing parent directories, returns fresh output buffers, preserves symlinks without following them, and remains immutable for its complete lifetime.

Shared reader conformance

Official source implementations use the testing subpath to register the same reader-contract checks in their Vitest suites. Install its exact testing peers in the implementing package:

pnpm add -D vitest@4.1.10 web-utils-kit@1.3.1

import {
  describeRepositoryReaderConformance,
  type IRepositoryReaderConformanceFixture,
} from '@moldea.ai/repository/testing';

export const registerReaderConformance = <TPath extends string>(
  fixture: IRepositoryReaderConformanceFixture<TPath>,
): void => {
  describeRepositoryReaderConformance('provider', fixture);
};

The peers are optional for ordinary package installation and are required only when importing @moldea.ai/repository/testing. The testing entry point registers tests but does not access a repository source itself.

Development

From the monorepo root:

pnpm --filter @moldea.ai/repository typecheck
pnpm --filter @moldea.ai/repository build
pnpm --filter @moldea.ai/repository test:unit
pnpm --filter @moldea.ai/repository test:integration
pnpm --filter @moldea.ai/repository test

Unit and integration tests are colocated with the source modules they exercise. The test command runs both suites. The shared reader conformance suite is published from this project for official reader implementations. Repository-format fixtures and diagnostics belong to @moldea.ai/core, not this package.