Grand Central Core

Core library for generating infrastructure configurations from OAM-style specifications.

Features

• YAML-based infrastructure specification
• Multi-environment support (dev, prod, etc.)
• 3-layer configuration merge (Global → Project → Spec)
• Component type routing (e.g., service → app, postgres → datastores)

Installation

npm install

Quick Start

1. Create a project definition in specs/infra/grand.central.core.yaml.
2. Run the generator:

   ./scripts/grand-central-core generate

3. Find generated artifacts in infra/.

CLI Usage

Command: generate-infra (aliases: generate, gen)

Generates infrastructure artifacts from an input specification.

Syntax:

./scripts/grand-central-core generate [options]

Options:

| Option | Alias | Description | Default | |--------|-------|-------------|---------| | --project-root | -p | Path to the project root | process.cwd() | | --input-spec | -i | Path to input spec file (relative to root) | specs/infra/grand.central.core.yaml | | --output-dir | -o | Directory to output artifacts | infra/ | | --dry-run | | Validate and normalize without writing files | false | | --help | | Show help message | | | --version | | Show version number | |

Examples:

# Default usage (looks for specs/infra/grand.central.core.yaml)
./scripts/grand-central-core generate

# Custom spec location
./scripts/grand-central-core generate -i my-spec.yaml

# Dry run to validate spec only
./scripts/grand-central-core gen --dry-run

Command: generate-docs

Generates a Markdown reference of the supported input specification schema and available components.

Syntax:

./scripts/grand-central-core generate-docs [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | --out | Output file path | docs/spec-reference.md |

Example:

# Generate docs/spec-reference.md (default)
./scripts/grand-central-core generate-docs

Input Specification Format

Input specs are YAML files describing the application and its components.

version: '1.0'
app:
  name: "my-app"
  blueprint: "service"

environments:
  - name: "dev"
  - name: "prod"

components:
  - name: "api"
    type: "service"
    properties:
      image: "my-app:latest"
      port: 8080
    traits:
      - type: "lifecycle"
        properties: { enabled: true }
      - type: "env-binding"
        properties:
          environments:
            dev: { replicas: 1 }
            prod: { replicas: 3 }

relations:
  - from: "api"
    to: "db"
    kind: "connects"

Output Artifacts

The generator produces split artifact files tailored for different infrastructure provisioners:

• app.hudson.yaml: Contains service, worker, frontend, job, batch components.
• datastores.hudson.yaml: Contains postgres, redis, mysql, mongo, dynamodb, s3, bucket.
• queues.hudson.yaml: Contains queue, topic, stream, kafka, rabbitmq.

Library API

You can use the core logic programmatically:

import { compileProject, generateArtifacts } from 'grand-central-core';

// 1. Compile (Load -> Validate -> Normalize)
const result = compileProject('/path/to/project', '/path/to/spec.yaml');

if (result.success) {
    // 2. Generate
    generateArtifacts(result.spec, '/path/to/output', '/path/to/source.yaml');
}

Architecture

The library operates in a pipeline:

1. Input Specs: Zod-validated YAML parsing.
2. Env Resolver: Calculates component state per environment (Enabled/Disabled + Overrides).
3. Compiler: Validates and normalizes the spec into a deterministic structure.
4. Output Artifacts: Partitions components into target-specific files.

Testing

The project maintains high test coverage (~95%) using Jest.

npm test

Current Status: 38 tests passing (Unit + Integration).

Development Workflow

1. Modify Source: Edit files in src/.
2. Test: Run npm test to verify changes.
3. Build: Run npm run build to compile TypeScript and copy assets.
4. Verify CLI: Run the CLI against a test project to ensure end-to-end functionality.

Releasing

This project is consumed via Git dependencies. To release a new version:

1. Release: Run a single command to test, build, update docs, tag, and push:

   npm version patch  # or minor, major

   What happens automatically:

   1. preversion: Runs tests. Stops if they fail.
   2. version: Builds project, regenerates docs/spec-reference.md, and adds it to the commit.
   3. postversion: Pushes the new commit and tag to GitHub.

2. Update Consumers: In the consumer project:

   npm install git+ssh://[email protected]/rakeyshgidwani/grand-central-core.git#vX.Y.Z