@garrick0/c2-core-application

CheckEngine and port interfaces for the C2 check system.

Overview

This package contains the application layer of the C2 architecture. It provides:

• CheckEngine: Pure check execution engine
• Port interfaces: Contracts that plugins implement (IObserverPort)
• Plugin descriptors: C2PluginDescriptor for declaring plugin capabilities

Installation

npm install @garrick0/c2-core-application

Key Concepts

CheckEngine

The core execution engine that runs checks against observables. It has no knowledge of DI containers or configuration loading - all dependencies are passed explicitly.

import { createCheckEngine } from '@garrick0/c2-core-application';

const engine = createCheckEngine({
  observers: [gitObserver, fsObserver],
});

const result = await engine.execute({
  context: '/path/to/project',
  activeChecks: resolvedChecks,
});

console.log(`Ran ${result.summary.total} checks`);
console.log(`Passed: ${result.summary.passed}`);
console.log(`Failed: ${result.summary.failed}`);

Ports

Ports are interfaces that define how the application layer interacts with external systems.

IObserverPort

Interface for observing external state and producing Observable snapshots.

interface IObserverPort<TData = unknown> {
  readonly name: string;
  readonly observableType: string;  // 'git', 'filesystem', etc.
  observe(config: ObserverConfig): AsyncResult<Observable<TData>, ObserverError>;
  canObserve?(context: string): Promise<boolean>;
}

Plugin Descriptors

Plugins declare their capabilities using C2PluginDescriptor:

interface C2PluginDescriptor {
  readonly name: string;
  readonly version?: string;
  readonly description?: string;
  readonly observers?: readonly IObserverPort[];
  readonly checks?: readonly CheckDefinition[];
  readonly profiles?: readonly ProfileDefinition[];
}

API Reference

Exports

// Re-export domain types for convenience
export * from '@garrick0/c2-core-domain';

// Engine
export { CheckEngine, createCheckEngine } from './engine/CheckEngine';
export type { CheckEngineOptions, ExecuteInput, ExecuteOutput } from './engine/CheckEngine';

// Ports
export type { IObserverPort, ObserverConfig, ObserverError } from './ports/IObserverPort';
export type { IEnvironmentConfig } from './ports/IEnvironmentConfig';

// Plugin types
export type { C2PluginDescriptor } from './kernel/PluginDescriptor';
export { validatePluginDescriptor } from './kernel/PluginDescriptor';

ExecuteOutput

interface ExecuteOutput {
  results: CheckResult[];
  summary: CheckSummary;
  durationMs: number;
  observables: ObservableInfo[];
  observerFailures: ObserverFailure[];
}

Usage Example

import {
  createCheckEngine,
  type IObserverPort,
  type C2PluginDescriptor,
} from '@garrick0/c2-core-application';

// Create an observer (typically from a feature plugin)
const myObserver: IObserverPort<MyData> = {
  name: 'my-observer',
  observableType: 'my-type',
  async observe(config) {
    const data = await fetchData(config.context);
    return { ok: true, value: new MyObservable(data) };
  },
};

// Create engine with observers
const engine = createCheckEngine({
  observers: [myObserver],
});

// Execute checks
const result = await engine.execute({
  context: '/path/to/project',
  activeChecks: [
    {
      id: 'my:check',
      name: 'My Check',
      observableType: 'my-type',
      query: { operation: 'someOperation' },
      mustBe: true,
      message: 'Check failed',
      severity: 'error',
    },
  ],
});

// Handle results
for (const check of result.results) {
  if (!check.passed && check.violation) {
    console.error(`[${check.violation.severity}] ${check.violation.message}`);
  }
}

Creating a Plugin

Plugins provide observers, check definitions, and profiles:

// my-plugin/register.ts
import type { C2PluginDescriptor, IObserverPort } from '@garrick0/c2-core-application';

class MyObserver implements IObserverPort<MyData> {
  readonly name = 'my-observer';
  readonly observableType = 'my-feature';

  async observe(config: ObserverConfig) {
    const data = await readMyData(config.context);
    return { ok: true, value: new MyObservable(data) };
  }
}

export function createMyPlugin(): C2PluginDescriptor {
  return {
    name: 'my-plugin',
    version: '1.0.0',
    description: 'My custom checks',
    observers: [new MyObserver()],
    checks: [myCheckDefinition],
    profiles: [myProfile],
  };
}

Architecture

This package sits in the application layer:

c2-cli → c2 → core-application (this package) → core-domain
                         ↓
                observable-git (plugin)

It depends only on @garrick0/c2-core-domain and defines interfaces that outer layers implement.

Development

# Build
npx nx build @garrick0/c2-core-application

# Test
npx nx test @garrick0/c2-core-application

# Lint
npx nx lint @garrick0/c2-core-application

License

MIT