tilt-ts-core/README.md

A TypeScript implementation of a Tilt-like development tool for Kubernetes live development workflows

# tilt-ts-core

A TypeScript implementation of a Tilt-like development tool that provides live development workflows for Kubernetes applications.

## Features

- **Docker Build**: Build and push Docker images to registry
- **Dagger Build**: Alternative build system using Dagger (optional)
- **Kubernetes Integration**: Apply YAML with automatic image reference rewriting
- **Live Updates**: File watching with live sync and command execution in pods
- **OpenTelemetry Logging**: Structured logging with contextual information

## Installation

```bash
npm install tilt-ts-core
```

## Quick Start

Create a `tiltfile.ts` in your project root:

```typescript
import { docker_build, k8s_yaml, live_update, sync, runStep } from "tilt-ts-core";

// Build Docker image with live update capability
const image = docker_build("myapp", ".", {
  live_update: [
    sync("./src", "/app/src"),
    runStep("npm run build", { triggers: ["package.json"] })
  ]
});

// Apply Kubernetes YAML
k8s_yaml("k8s/deployment.yaml", { images: [image] });

// Start live update watcher
live_update();
```

Run your development workflow:

```bash
bun run dev  # or node tiltfile.ts
```

## API Reference

### Build Functions

#### `docker_build(name, context, options?)`

Builds a Docker image and pushes it to the configured registry.

```typescript
const image = docker_build("myapp", ".", {
  dockerfile: "Dockerfile.dev",
  live_update: [
    sync("./src", "/app/src"),
    runStep("npm install", { triggers: ["package.json"] })
  ]
});
```

#### `dagger_build(name, context, options?)`

Alternative build using Dagger pipeline.

```typescript
const image = dagger_build("myapp", ".", {
  live_update: [sync("./src", "/app/src")]
});
```

### Kubernetes Functions

#### `k8s_yaml(path, options?)`

Applies Kubernetes YAML with image reference rewriting.

```typescript
k8s_yaml("k8s/deployment.yaml", {
  images: [image],
  namespace: "development"
});
```

### Live Update Functions

#### `live_update()`

Starts the live update file watcher for all configured resources.

```typescript
live_update();
```

#### Helper Functions

##### `sync(local_path, container_path, options?)`

Creates a sync step for live updates.

```typescript
sync("./src", "/app/src", { exclude: ["node_modules"] })
```

##### `runStep(command, options?)`

Creates a run step that executes commands when files change.

```typescript
runStep("npm run build", {
  triggers: ["package.json", "src/**/*.ts"],
  dir: "/app"
})
```

## Configuration

### Environment Variables

- `REGISTRY_URL`: Docker registry URL (default: `localhost:36269`)
- `K8S_CONTEXT`: Kubernetes context to use
- `SEMRESATTRS_SERVICE_NAME`: OpenTelemetry service name

### Prerequisites

- Kubernetes cluster with kubectl configured
- Docker registry accessible from cluster
- For k3d: Local cluster named "k3d-ecosys-local-dev"

## Live Update System

The live update engine supports two types of operations:

### Sync Steps
Synchronize files from local filesystem to pod containers:

```typescript
sync("./src", "/app/src")  // Basic sync
sync("./config", "/app/config", { exclude: ["*.tmp"] })  // With exclusions
```

### Run Steps  
Execute commands in pods when specific files change:

```typescript
runStep("npm run build", { triggers: ["package.json"] })
runStep("npm test", { triggers: ["src/**/*.test.ts"], dir: "/app" })
```

## Logging

Uses OpenTelemetry structured logging with contextual information:

```typescript
import { logger } from "tilt-ts-core";

logger.emit({
  severityText: "INFO",
  body: "Build completed",
  attributes: { image: "myapp:latest", duration: 1234 }
});
```

## Observability Setup

### Enable OpenTelemetry Instrumentation

To enable full observability with tracing and structured logging:

```typescript
// Import the instrumentation before your main application code
import "tilt-ts-core/instrumentation";

// Your application code
import { docker_build, k8s_yaml, live_update } from "tilt-ts-core";
// ... rest of your code
```

### Using Node.js --require flag

For Node.js applications, you can also enable instrumentation using the `--require` flag:

```bash
node --require tilt-ts-core/instrumentation your-tiltfile.js
```

### Environment Variables

Configure OpenTelemetry through environment variables:

```bash
# Set service name for tracing
export SEMRESATTRS_SERVICE_NAME="my-tilt-project"

# OpenTelemetry endpoint (defaults to localhost:4318)
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"

# Enable/disable specific signals
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
```

### Observability Stack

For a complete observability setup with Grafana, Loki, and OpenTelemetry collector:

```bash
npm install tilt-ts-observability
npm run otel  # starts the observability stack
```

This provides:
- **Grafana Dashboard**: http://localhost:3000 (admin/admin)
- **Structured Logs**: Viewable in Grafana with filtering and search
- **Tracing**: OpenTelemetry traces for debugging performance issues
- **Metrics**: System and application metrics collection

## Examples

Check the `examples/` directory for complete usage examples:

- `examples/nginx/` - Simple nginx application with live updates

## License

MIT