npm package: @garrick0/c2-core-application
Description: C2 Core Application - Ports and use cases for the check system
Author: garrick0
Latest version: 6.1.0

# @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

```bash
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.

```typescript
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.

```typescript
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`:

```typescript
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

```typescript
// 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

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

## Usage Example

```typescript
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:

```typescript
// 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

```bash
# 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