@intentius/chant-lexicon-docker 0.1.0

package/src/serializer.ts

@@ -0,0 +1,322 @@
+/**
+ * Docker lexicon serializer.
+ *
+ * Splits entities into two output domains:
+ * - Docker::Compose::* → docker-compose.yml (primary output)
+ * - Docker::Dockerfile → Dockerfile.{name} (per-file entries in SerializerResult)
+ *
+ * Default labels (DEFAULT_LABELS_MARKER) are merged into every service's
+ * labels map but are not emitted as standalone documents.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+import { emitYAML } from "@intentius/chant/yaml";
+
+// ── Helpers ───────────────────────────────────────────────────────
+
+const DEFAULT_LABELS_MARKER_KEY = Symbol.for("docker.defaultLabels");
+const DEFAULT_ANNOTATIONS_MARKER_KEY = Symbol.for("docker.defaultAnnotations");
+
+function isDefaultLabelsEntity(entity: Declarable): boolean {
+  return DEFAULT_LABELS_MARKER_KEY in entity;
+}
+
+function isDefaultAnnotationsEntity(entity: Declarable): boolean {
+  return DEFAULT_ANNOTATIONS_MARKER_KEY in entity;
+}
+
+function getProps(entity: Declarable): Record<string, unknown> {
+  if ("props" in entity && typeof entity.props === "object" && entity.props !== null) {
+    return entity.props as Record<string, unknown>;
+  }
+  return {};
+}
+
+// ── Intrinsic preprocessing ───────────────────────────────────────
+
+function preprocessIntrinsics(value: unknown): unknown {
+  if (value === null || value === undefined) return value;
+
+  if (typeof value === "object" && INTRINSIC_MARKER in (value as object)) {
+    if ("toJSON" in (value as object) && typeof (value as { toJSON?: unknown }).toJSON === "function") {
+      return ((value as { toJSON(): unknown }).toJSON)();
+    }
+  }
+
+  if (typeof value === "object" && value !== null && "entityType" in (value as object)) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(preprocessIntrinsics);
+  }
+
+  if (typeof value === "object") {
+    const result: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      result[k] = preprocessIntrinsics(v);
+    }
+    return result;
+  }
+
+  return value;
+}
+
+// ── Visitor ───────────────────────────────────────────────────────
+
+function dockerVisitor(entityNames: Map<Declarable, string>): SerializerVisitor {
+  return {
+    attrRef: (name, _attr) => name,
+    // For Dockerfile references, emit the filename
+    resourceRef: (name) => `Dockerfile.${name}`,
+    propertyDeclarable: (entity, walk) => {
+      const props = getProps(entity);
+      const result: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(props)) {
+        if (value !== undefined) {
+          result[key] = walk(value);
+        }
+      }
+      return Object.keys(result).length > 0 ? result : undefined;
+    },
+  };
+}
+
+function toYAMLValue(value: unknown, entityNames: Map<Declarable, string>): unknown {
+  const preprocessed = preprocessIntrinsics(value);
+  return walkValue(preprocessed, entityNames, dockerVisitor(entityNames));
+}
+
+// ── Compose serialization ─────────────────────────────────────────
+
+function serializeCompose(
+  services: Map<string, Declarable>,
+  volumes: Map<string, Declarable>,
+  networks: Map<string, Declarable>,
+  configs: Map<string, Declarable>,
+  secrets: Map<string, Declarable>,
+  defaultLabels: Record<string, string>,
+  entityNames: Map<Declarable, string>,
+): string {
+  const doc: Record<string, unknown> = {};
+
+  if (services.size > 0) {
+    const servicesSection: Record<string, unknown> = {};
+    for (const [name, entity] of services) {
+      const props = toYAMLValue(getProps(entity), entityNames) as Record<string, unknown>;
+      // Merge default labels into service labels
+      if (Object.keys(defaultLabels).length > 0) {
+        const existing = (props.labels as Record<string, string>) ?? {};
+        props.labels = { ...defaultLabels, ...existing };
+      }
+      // Remove undefined values
+      const cleaned: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(props)) {
+        if (v !== undefined && v !== null) cleaned[k] = v;
+      }
+      servicesSection[name] = cleaned;
+    }
+    doc.services = servicesSection;
+  }
+
+  if (volumes.size > 0) {
+    const volumesSection: Record<string, unknown> = {};
+    for (const [name, entity] of volumes) {
+      const props = toYAMLValue(getProps(entity), entityNames) as Record<string, unknown>;
+      const cleaned: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(props)) {
+        if (v !== undefined && v !== null) cleaned[k] = v;
+      }
+      volumesSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
+    }
+    doc.volumes = volumesSection;
+  }
+
+  if (networks.size > 0) {
+    const networksSection: Record<string, unknown> = {};
+    for (const [name, entity] of networks) {
+      const props = toYAMLValue(getProps(entity), entityNames) as Record<string, unknown>;
+      const cleaned: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(props)) {
+        if (v !== undefined && v !== null) cleaned[k] = v;
+      }
+      networksSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
+    }
+    doc.networks = networksSection;
+  }
+
+  if (configs.size > 0) {
+    const configsSection: Record<string, unknown> = {};
+    for (const [name, entity] of configs) {
+      const props = toYAMLValue(getProps(entity), entityNames) as Record<string, unknown>;
+      const cleaned: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(props)) {
+        if (v !== undefined && v !== null) cleaned[k] = v;
+      }
+      configsSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
+    }
+    doc.configs = configsSection;
+  }
+
+  if (secrets.size > 0) {
+    const secretsSection: Record<string, unknown> = {};
+    for (const [name, entity] of secrets) {
+      const props = toYAMLValue(getProps(entity), entityNames) as Record<string, unknown>;
+      const cleaned: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(props)) {
+        if (v !== undefined && v !== null) cleaned[k] = v;
+      }
+      secretsSection[name] = Object.keys(cleaned).length > 0 ? cleaned : null;
+    }
+    doc.secrets = secretsSection;
+  }
+
+  return emitComposeDocument(doc);
+}
+
+function emitComposeDocument(doc: Record<string, unknown>): string {
+  if (Object.keys(doc).length === 0) return "\n";
+
+  const ORDER = ["services", "volumes", "networks", "configs", "secrets"];
+  const sections: string[] = [];
+  const emitted = new Set<string>();
+
+  for (const key of ORDER) {
+    if (key in doc && doc[key] !== undefined) {
+      emitted.add(key);
+      sections.push(`${key}:` + emitYAML(doc[key], 1));
+    }
+  }
+
+  for (const [key, value] of Object.entries(doc)) {
+    if (!emitted.has(key) && value !== undefined) {
+      sections.push(`${key}:` + emitYAML(value, 1));
+    }
+  }
+
+  return sections.join("\n\n") + "\n";
+}
+
+// ── Dockerfile serialization ──────────────────────────────────────
+
+function serializeDockerfile(entity: Declarable): string {
+  const props = getProps(entity);
+  const lines: string[] = [];
+
+  // Multi-stage build via stages[]
+  if (Array.isArray(props.stages) && props.stages.length > 0) {
+    for (const stage of props.stages as Array<Record<string, unknown>>) {
+      emitStage(stage, lines);
+    }
+    return lines.join("\n") + "\n";
+  }
+
+  // Single-stage build
+  emitStage(props, lines);
+  return lines.join("\n") + "\n";
+}
+
+function emitStage(stage: Record<string, unknown>, lines: string[]): void {
+  // FROM must be first
+  if (stage.from) {
+    const as = stage.as ? ` AS ${stage.as}` : "";
+    lines.push(`FROM ${stage.from}${as}`);
+  }
+
+  const INSTRUCTION_ORDER = [
+    "arg", "env", "workdir", "user", "run", "copy", "add",
+    "expose", "volume", "label", "entrypoint", "cmd", "healthcheck",
+  ];
+
+  for (const instr of INSTRUCTION_ORDER) {
+    const value = stage[instr];
+    if (value === undefined || value === null) continue;
+
+    const keyword = instr.toUpperCase();
+
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        lines.push(`${keyword} ${item}`);
+      }
+    } else if (typeof value === "string") {
+      lines.push(`${keyword} ${value}`);
+    }
+  }
+}
+
+// ── Serializer ────────────────────────────────────────────────────
+
+export const dockerSerializer: Serializer = {
+  name: "docker",
+  rulePrefix: "DKR",
+
+  serialize(
+    entities: Map<string, Declarable>,
+    _outputs?: LexiconOutput[],
+  ): string | SerializerResult {
+    const entityNames = new Map<Declarable, string>();
+    for (const [name, entity] of entities) {
+      entityNames.set(entity, name);
+    }
+
+    const services = new Map<string, Declarable>();
+    const volumes = new Map<string, Declarable>();
+    const networks = new Map<string, Declarable>();
+    const configs = new Map<string, Declarable>();
+    const secrets = new Map<string, Declarable>();
+    const dockerfiles = new Map<string, Declarable>();
+    let defaultLabels: Record<string, string> = {};
+
+    for (const [name, entity] of entities) {
+      // Skip property-kind entities
+      if (isPropertyDeclarable(entity)) continue;
+
+      // Skip default labels/annotations markers — collect instead
+      if (isDefaultLabelsEntity(entity)) {
+        const props = getProps(entity);
+        defaultLabels = { ...defaultLabels, ...(props.labels as Record<string, string> ?? {}) };
+        continue;
+      }
+      if (isDefaultAnnotationsEntity(entity)) {
+        continue;
+      }
+
+      const et = (entity as Record<string, unknown>).entityType as string;
+
+      if (et === "Docker::Compose::Service") {
+        services.set(name, entity);
+      } else if (et === "Docker::Compose::Volume") {
+        volumes.set(name, entity);
+      } else if (et === "Docker::Compose::Network") {
+        networks.set(name, entity);
+      } else if (et === "Docker::Compose::Config") {
+        configs.set(name, entity);
+      } else if (et === "Docker::Compose::Secret") {
+        secrets.set(name, entity);
+      } else if (et === "Docker::Dockerfile") {
+        dockerfiles.set(name, entity);
+      }
+    }
+
+    const composeYaml = serializeCompose(
+      services, volumes, networks, configs, secrets,
+      defaultLabels, entityNames,
+    );
+
+    if (dockerfiles.size === 0) {
+      return composeYaml;
+    }
+
+    const files: Record<string, string> = {};
+    for (const [name, entity] of dockerfiles) {
+      files[`Dockerfile.${name}`] = serializeDockerfile(entity);
+    }
+
+    return { primary: composeYaml, files };
+  },
+};

package/src/skills/chant-docker-patterns.md

@@ -0,0 +1,153 @@
+# chant-docker-patterns
+
+Common Docker Compose and Dockerfile patterns using `@intentius/chant-lexicon-docker`.
+
+## Database service with volume
+
+```typescript
+import { Service, Volume } from "@intentius/chant-lexicon-docker";
+
+export const postgres = new Service({
+  image: "postgres:16-alpine",
+  environment: {
+    POSTGRES_DB: "myapp",
+    POSTGRES_USER: "myapp",
+    POSTGRES_PASSWORD: env("POSTGRES_PASSWORD", { required: true }),
+  },
+  volumes: ["pgdata:/var/lib/postgresql/data"],
+  restart: "unless-stopped",
+  healthcheck: {
+    test: ["CMD-SHELL", "pg_isready -U myapp"],
+    interval: "10s",
+    timeout: "5s",
+    retries: 5,
+  },
+});
+
+export const pgdata = new Volume({});
+```
+
+## Redis cache
+
+```typescript
+export const redis = new Service({
+  image: "redis:7-alpine",
+  volumes: ["redisdata:/data"],
+  command: "redis-server --appendonly yes",
+  restart: "unless-stopped",
+});
+export const redisdata = new Volume({});
+```
+
+## Reverse proxy (nginx)
+
+```typescript
+export const nginx = new Service({
+  image: "nginx:1.25-alpine",
+  ports: ["80:80", "443:443"],
+  volumes: ["./nginx.conf:/etc/nginx/nginx.conf:ro", "./certs:/etc/ssl/certs:ro"],
+  depends_on: ["api"],
+  restart: "unless-stopped",
+});
+```
+
+## Multi-stage Node.js Dockerfile
+
+```typescript
+export const nodeApp = new Dockerfile({
+  stages: [
+    {
+      from: "node:20-alpine",
+      as: "deps",
+      workdir: "/app",
+      copy: ["package*.json ./"],
+      run: ["npm ci --only=production"],
+    },
+    {
+      from: "node:20-alpine",
+      as: "build",
+      workdir: "/app",
+      copy: ["--from=deps /app/node_modules ./node_modules", ". ."],
+      run: ["npm run build"],
+    },
+    {
+      from: "node:20-alpine",
+      workdir: "/app",
+      copy: [
+        "--from=deps /app/node_modules ./node_modules",
+        "--from=build /app/dist ./dist",
+      ],
+      user: "node",
+      expose: ["3000"],
+      cmd: `["node", "dist/index.js"]`,
+    },
+  ],
+});
+```
+
+## Python service with virtualenv
+
+```typescript
+export const pythonApp = new Dockerfile({
+  from: "python:3.12-slim",
+  workdir: "/app",
+  env: ["PYTHONUNBUFFERED=1", "PYTHONDONTWRITEBYTECODE=1"],
+  copy: ["requirements.txt ."],
+  run: [
+    "pip install --no-cache-dir --no-deps -r requirements.txt",
+  ],
+  copy: [". ."],
+  user: "1000:1000",
+  cmd: `["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]`,
+});
+```
+
+## Network isolation
+
+```typescript
+import { Service, Network } from "@intentius/chant-lexicon-docker";
+
+export const internal = new Network({ driver: "bridge", internal: true });
+export const external = new Network({ driver: "bridge" });
+
+export const api = new Service({
+  image: "myapi:1.0",
+  networks: ["external", "internal"],
+});
+export const db = new Service({
+  image: "postgres:16-alpine",
+  networks: ["internal"],  // only reachable via internal network
+});
+```
+
+## Secrets and configs
+
+```typescript
+import { Service, DockerSecret, DockerConfig } from "@intentius/chant-lexicon-docker";
+
+export const dbPassword = new DockerSecret({ file: "./secrets/db-password.txt" });
+export const appConfig = new DockerConfig({ file: "./config/app.yaml" });
+
+export const app = new Service({
+  image: "myapp:1.0",
+  secrets: ["dbPassword"],
+  configs: ["appConfig"],
+});
+```
+
+## Environment interpolation patterns
+
+```typescript
+import { env } from "@intentius/chant-lexicon-docker";
+
+// Dev vs prod toggle:
+export const api = new Service({
+  image: env("API_IMAGE", { default: "myapp:latest" }),
+  environment: {
+    LOG_LEVEL: env("LOG_LEVEL", { default: "info" }),
+    WORKERS: env("WORKERS", { default: "4" }),
+    SECRET_KEY: env("SECRET_KEY", { required: true }),
+    SENTRY_DSN: env("SENTRY_DSN", { default: "" }),
+  },
+});
+```

package/src/skills/chant-docker.md

@@ -0,0 +1,129 @@
+# chant-docker
+
+You are helping a developer define Docker Compose services and Dockerfiles using the `@intentius/chant-lexicon-docker` library.
+
+## Core types
+
+```typescript
+import { Service, Volume, Network, Dockerfile, env, defaultLabels } from "@intentius/chant-lexicon-docker";
+```
+
+## Service — docker-compose.yml services:
+
+```typescript
+export const api = new Service({
+  image: "myapp:1.0",
+  ports: ["8080:8080"],
+  environment: {
+    NODE_ENV: "production",
+    DB_URL: env("DATABASE_URL", { required: true }),
+  },
+  depends_on: ["db"],
+  restart: "unless-stopped",
+  healthcheck: {
+    test: ["CMD", "curl", "-f", "http://localhost:8080/health"],
+    interval: "30s",
+    timeout: "10s",
+    retries: 3,
+  },
+});
+```
+
+## Volume — top-level named volume:
+
+```typescript
+export const pgdata = new Volume({});
+// With driver options:
+export const nfsdata = new Volume({ driver: "local", driver_opts: { type: "nfs", o: "addr=..." } });
+```
+
+## Dockerfile — generates Dockerfile.{name}:
+
+```typescript
+// Single-stage:
+export const builder = new Dockerfile({
+  from: "node:20-alpine",
+  workdir: "/app",
+  copy: ["package*.json ./"],
+  run: ["npm ci --only=production"],
+  user: "node",
+  cmd: `["node", "dist/index.js"]`,
+});
+
+// Multi-stage build:
+export const app = new Dockerfile({
+  stages: [
+    {
+      from: "node:20-alpine",
+      as: "build",
+      workdir: "/app",
+      copy: ["package*.json ./"],
+      run: ["npm ci", "npm run build"],
+    },
+    {
+      from: "node:20-alpine",
+      workdir: "/app",
+      copy: ["--from=build /app/dist ./dist", "--from=build /app/node_modules ./node_modules"],
+      user: "node",
+      cmd: `["node", "dist/index.js"]`,
+    },
+  ],
+});
+```
+
+## Variable interpolation with env():
+
+```typescript
+import { env } from "@intentius/chant-lexicon-docker";
+
+// ${VAR} — required, no default:
+env("DATABASE_URL")
+
+// ${VAR:-default} — use default if unset:
+env("LOG_LEVEL", { default: "info" })
+
+// ${VAR:?message} — fail with error if unset:
+env("API_SECRET", { required: true })
+env("API_SECRET", { errorMessage: "API_SECRET must be set in .env" })
+
+// ${VAR:+value} — substitute value if VAR is set:
+env("DEBUG", { ifSet: "verbose" })
+```
+
+## Default labels (injected into all services):
+
+```typescript
+export const labels = defaultLabels({
+  "com.example.team": "platform",
+  "com.example.managed-by": "chant",
+  "com.example.version": "1.0.0",
+});
+```
+
+## Service → Dockerfile cross-reference:
+
+```typescript
+// The serializer emits "Dockerfile.builder" as the filename.
+// Reference it in the service build config:
+export const api = new Service({
+  build: {
+    context: ".",
+    dockerfile: "Dockerfile.builder",  // matches the Dockerfile entity name
+  },
+  ports: ["8080:8080"],
+});
+export const builder = new Dockerfile({ from: "node:20-alpine", ... });
+```
+
+## Output structure
+
+- All Compose entities → `docker-compose.yml`
+- Each Dockerfile entity → `Dockerfile.{name}`
+
+## Key rules
+
+- `DKRS001`: Never use `:latest` image tags in source — use explicit versions
+- `DKRD001`: Post-synth: no `:latest` images in generated YAML
+- `DKRD002`: Post-synth: no unused named volumes
+- `DKRD003`: Post-synth: SSH port 22 not exposed externally
+- `DKRD010–012`: Dockerfile best practices (apt recommends, COPY vs ADD, USER)

package/src/spec/fetch-compose.ts

@@ -0,0 +1,35 @@
+/**
+ * Fetch and cache the Compose Spec JSON Schema.
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache } from "@intentius/chant/codegen/fetch";
+import { COMPOSE_SPEC_URL, COMPOSE_SPEC_CACHE } from "../codegen/versions";
+
+export function getCachePath(): string {
+  return join(homedir(), ".chant", COMPOSE_SPEC_CACHE);
+}
+
+/**
+ * Fetch the Compose Spec JSON Schema, with local caching.
+ */
+export async function fetchComposeSpec(force?: boolean): Promise<Buffer> {
+  return fetchWithCache(
+    {
+      url: COMPOSE_SPEC_URL,
+      cacheFile: getCachePath(),
+    },
+    force,
+  );
+}
+
+/**
+ * Fetch compose spec as a Map keyed by entity type — for generatePipeline.
+ */
+export async function fetchComposeSchemas(force?: boolean): Promise<Map<string, Buffer>> {
+  const data = await fetchComposeSpec(force);
+  const schemas = new Map<string, Buffer>();
+  schemas.set("Docker::Compose::Service", data);
+  return schemas;
+}

package/src/spec/fetch-engine.ts

@@ -0,0 +1,25 @@
+/**
+ * Fetch and cache the Docker Engine API OpenAPI spec.
+ */
+
+import { join } from "path";
+import { homedir } from "os";
+import { fetchWithCache } from "@intentius/chant/codegen/fetch";
+import { ENGINE_API_URL, ENGINE_API_CACHE } from "../codegen/versions";
+
+export function getCachePath(): string {
+  return join(homedir(), ".chant", ENGINE_API_CACHE);
+}
+
+/**
+ * Fetch the Docker Engine API swagger YAML, with local caching.
+ */
+export async function fetchEngineApi(force?: boolean): Promise<Buffer> {
+  return fetchWithCache(
+    {
+      url: ENGINE_API_URL,
+      cacheFile: getCachePath(),
+    },
+    force,
+  );
+}