Skip to content

data-model.md

Latest commit

 

History

History
159 lines (126 loc) · 4.84 KB

data-model.md

File metadata and controls

159 lines (126 loc) · 4.84 KB

Data Model: cc-deck Build Pipeline

Date: 2026-03-12 Branch: 018-build-manifest

Entities

Build Directory

A self-contained directory created by cc-deck build init.

<build-dir>/
  cc-deck-build.yaml        # Manifest (source of truth)
  Containerfile              # Generated by AI (gitignored)
  .build-context/            # Ephemeral build artifacts (gitignored)
  .gitignore
  .claude/
    commands/                # AI-driven commands (embedded at init)
      cc-deck.extract.md
      cc-deck.plugin.md
      cc-deck.mcp.md
      cc-deck.containerfile.md
      cc-deck.publish.md
    scripts/                 # Helper scripts (embedded at init)
      validate-manifest.sh
      update-manifest.sh

Manifest (cc-deck-build.yaml)

Section Purpose Required
version Schema version (currently 1) Yes
image Image name, tag, base image Yes
tools Free-form tool requirements No
sources Repository provenance No
plugins Claude Code plugins No
mcp MCP server sidecars No
github_tools GitHub release downloads No
settings CC config to bake in No

image

Field Type Description
name string Image name (e.g., my-team/cc-deck-dev)
tag string Default tag (default: latest)
base string Base image (default: ghcr.io/rhuss/cc-deck-base:latest)

tools

List of free-form strings. Each entry describes a tool requirement in human-readable text, resolved to install commands by the AI during Containerfile generation.

Examples: "Go compiler >= 1.22", "Python 3.12 with uv", "protoc and buf CLI"

sources

Field Type Description
url string Repository URL
ref string Branch/tag reference
path string Local checkout path used during extraction
detected_tools list[string] Tools found in this repo
detected_from list[string] Files that contained the tool references

plugins

Field Type Description
name string Plugin name
source string marketplace or git:<url>

mcp

Field Type Description
name string Server name
image string Container image reference
transport string sse or stdio
port int Service port
auth.type string token, basic, oauth, none
auth.env_vars list[string] Required environment variable names
description string Human-readable description

github_tools

Field Type Description
repo string GitHub owner/repo
binary string Binary name after extraction

settings

Field Type Description
claude_md string Path to project CLAUDE.md
hooks string Path to hooks config JSON
zellij_config string current, vanilla, or custom path

MCP Label Schema

Labels on container images for auto-discovery by /cc-deck.mcp.

Label Type Description
cc-deck.mcp/name string Server name
cc-deck.mcp/version string Server version
cc-deck.mcp/transport string sse or stdio
cc-deck.mcp/port string Service port
cc-deck.mcp/auth-type string token, basic, oauth, none
cc-deck.mcp/auth-env-vars string Comma-separated env var names
cc-deck.mcp/description string Human-readable description
cc-deck.mcp/docs-url string Documentation URL

Containerfile (Generated)

Not a data entity but a derived artifact. Always starts with:

# GENERATED BY cc-deck.containerfile - DO NOT EDIT
# Regenerate with: claude /cc-deck.containerfile

Layer order (optimized for cache):

  1. Base image + system packages (changes rarely)
  2. Language-specific tools (changes occasionally)
  3. cc-deck self-install (Zellij + plugin + layouts)
  4. Claude Code install
  5. GitHub tools
  6. Plugins
  7. Configuration (changes often)

Relationships

Build Directory
  ├── contains Manifest (source of truth)
  │     ├── references Base Image
  │     ├── lists Tools
  │     ├── tracks Sources (provenance)
  │     ├── lists Plugins
  │     ├── lists MCP Servers
  │     ├── lists GitHub Tools
  │     └── references Settings
  ├── contains Containerfile (derived from Manifest by AI)
  └── contains AI Commands (embedded at init)

State Transitions

The build directory has a simple lifecycle:

[Empty] → init → [Scaffolded] → extract/plugin/mcp → [Populated]
[Populated] → containerfile → [Ready to Build]
[Ready to Build] → build → [Image Built]
[Image Built] → push → [Published]