feat: add asciinema demo generator with PS1 timing, comment step, and validation

- demo/generate.py: YAML-to-asciinema cast generator with cmd, prompt, pause,
  and comment step types; hierarchical PS1 resolution; validation pre-pass
- demo/demo.yaml: scripted demo for devcode CLI (open, template, ps commands)
- demo/demo.gif: generated demo GIF via agg
- demo/Makefile: downloads agg + JetBrains Mono font, generates cast and GIF
- tests/test_generate.py: 76 tests covering all step types, PS1 timing, validation

Author: dacrystal

.gitignore

@@ -174,3 +174,4 @@ poetry.toml
 pyrightconfig.json
 
 # End of https://www.toptal.com/developers/gitignore/api/python
+

README.md

@@ -19,6 +19,8 @@ Reusable Dev Containers for any project — without modifying the repository.
 
 ---
 
+![Alt text](demo/demo.gif)
+
 
 `devcode` is a CLI that opens any project in VS Code Dev Containers using reusable, local templates.
 

demo/.gitignore

@@ -0,0 +1,3 @@
+.fonts
+.agg
+demo.cast

demo/Makefile

@@ -0,0 +1,56 @@
+CAST      := demo.cast
+GIF       := demo.gif
+AGG       := .agg
+FONTS_DIR := .fonts
+
+# Detect platform for agg binary
+UNAME_S := $(shell uname -s)
+UNAME_M := $(shell uname -m)
+
+ifeq ($(UNAME_S),Linux)
+  ifeq ($(UNAME_M),x86_64)
+    AGG_ASSET := agg-x86_64-unknown-linux-gnu
+  else ifeq ($(UNAME_M),aarch64)
+    AGG_ASSET := agg-aarch64-unknown-linux-gnu
+  else
+    $(error Unsupported Linux architecture: $(UNAME_M))
+  endif
+else ifeq ($(UNAME_S),Darwin)
+  ifeq ($(UNAME_M),arm64)
+    AGG_ASSET := agg-aarch64-apple-darwin
+  else
+    AGG_ASSET := agg-x86_64-apple-darwin
+  endif
+else
+  $(error Unsupported OS: $(UNAME_S))
+endif
+
+AGG_URL  := https://github.com/asciinema/agg/releases/latest/download/$(AGG_ASSET)
+FONT_URL := https://github.com/JetBrains/JetBrainsMono/releases/download/v2.304/JetBrainsMono-2.304.zip
+
+.PHONY: all gif cast clean
+
+all: gif
+
+gif: $(GIF)
+
+$(GIF): $(CAST) $(AGG) $(FONTS_DIR)
+	./$(AGG) --font-dir $(FONTS_DIR) --renderer fontdue --font-family "JetBrains Mono" --rows 20 --cols 80 $(CAST) $(GIF)
+
+$(CAST): demo.yaml generate.py
+	uv run python generate.py
+
+$(AGG):
+	curl -fsSL -o $(AGG) $(AGG_URL)
+	chmod +x $(AGG)
+
+$(FONTS_DIR):
+	mkdir -p $(FONTS_DIR)
+	curl -fsSL -o $(FONTS_DIR)/JetBrainsMono.zip $(FONT_URL)
+	unzip -q -o $(FONTS_DIR)/JetBrainsMono.zip "fonts/ttf/*.ttf" -d $(FONTS_DIR)
+	mv $(FONTS_DIR)/fonts/ttf/*.ttf $(FONTS_DIR)/
+	rm -rf $(FONTS_DIR)/fonts $(FONTS_DIR)/JetBrainsMono.zip
+
+clean:
+	rm -f $(GIF) $(CAST) $(AGG)
+	rm -rf $(FONTS_DIR)

demo/demo.gif

@@ -0,0 +1,74 @@
+config:
+  width: 120
+  height: 30
+  title: "devcode demo"
+  ps1: "\x1b[92m❯ \x1b[0m"
+  typing_delay: 0.06
+  post_cmd_delay: 1.2
+  comment_color: "\x1b[93m"
+  between_demos:
+    delay: 2.0
+    clear: true
+
+demos:
+  - name: "Open a project"
+    steps:
+      - comment: "Create a new template"
+      - cmd: "devcode new dev"
+        output: |
+          Created template 'dev-test' at ~/.local/share/dev-code/templates/dev
+
+      - comment: "Open a project in VS Code using the template"
+      - cmd: "devcode open dev ~/projects/my-app"
+        output: "\x1b[32m Opening ~/projects/my-app in VS Code...\x1b[0m\n"
+
+  - name: "Manage templates"
+    steps:
+      - comment: "List existing templates"
+      - cmd: "devcode list"
+        output: |
+          dev-code
+
+      - comment: "Create another template"
+      - cmd: "devcode new demo"
+        output: |
+          Created template 'demo' at ~/.local/share/dev-code/templates/demo
+
+      - comment: "List templates again to confirm"
+      - cmd: "devcode list"
+        output: |
+          dev-code
+          demo
+
+      - comment: "Edit the template in VS Code"
+      - cmd: "devcode edit demo"
+        output: "\x1b[32m Opening 'demo' template in VS Code...\x1b[0m\n"
+
+  - name: "Container status"
+    steps:
+      - comment: "Show running containers"
+      - cmd: "devcode ps"
+        output: |
+          #  CONTAINER ID  TEMPLATE  PROJECT PATH                 STATUS
+          1  a1b9afa16218  dev       ~/projects/my-app            Up 3 min
+
+      - comment: "Show all containers including stopped ones"
+      - cmd: "devcode ps -a"
+        output: |
+          #  CONTAINER ID  TEMPLATE  PROJECT PATH                 STATUS
+          1  a1b2c3d4e5f6  claude    ~/projects/mk3serve          Exited (0) 2 weeks ago
+          2  9f8e7d6c5b4a  py-dev    ~/projects/py-app            Exited (0) 1 hours ago
+          3  a1b9afa16218  dev       ~/projects/my-app            Up 3 min
+
+      - comment: "Interactively pick a container to reopen"
+      - cmd: "devcode ps -a -i"
+        output: |
+          #  CONTAINER ID  TEMPLATE  PROJECT PATH                 STATUS
+          1  a1b2c3d4e5f6  claude    ~/projects/mk3serve          Exited (0) 2 weeks ago
+          2  9f8e7d6c5b4a  py-dev    ~/projects/py-app            Exited (0) 1 hours ago
+          3  a1b9afa16218  dev       ~/projects/my-app            Up 3 min
+
+          Open [1-3]: 
+
+      - prompt: "2"
+        output: "\x1b[32m Opening '~/projects/py-app' container in VS Code...\x1b[0m\n"

demo/demo.yaml

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Generate an asciinema v2 .cast file from a YAML demo script."""
+
+import json
+import sys
+from pathlib import Path
+
+import yaml
+
+_HERE = Path(__file__).parent
+
+
+def _validate(demos: list) -> None:
+    """Validate step sequences across all demos before generation begins.
+
+    Raises ValueError if any prompt step does not immediately follow a cmd step,
+    or if any comment step has a null value.
+    """
+    for demo in demos:
+        steps = demo.get("steps", [])
+        name = demo.get("name", "?")
+        for i, step in enumerate(steps):
+            if "comment" in step and step["comment"] is None:
+                raise ValueError(
+                    f"Demo '{name}' step {i}: 'comment' value must not be null"
+                )
+            if "prompt" in step:
+                prev = steps[i - 1] if i > 0 else {}
+                if i == 0 or "cmd" not in prev:
+                    prev_key = list(prev.keys())[0] if prev else "none"
+                    raise ValueError(
+                        f"Demo '{name}' step {i}: 'prompt' must immediately follow 'cmd' "
+                        f"(preceding step has key '{prev_key}')"
+                    )
+
+
+def _next_ps1(steps: list, from_idx: int, demo_ps1: str | None, global_ps1: str, fallback_step: dict) -> str:
+    """Return the resolved PS1 for the next cmd/comment step at or after from_idx.
+
+    Scans forward, skipping pause and prompt steps.
+    Falls back to fallback_step's resolved PS1 if no cmd/comment found.
+    """
+    for step in steps[from_idx:]:
+        if "cmd" in step or "comment" in step:
+            return next(v for v in (step.get("ps1"), demo_ps1, global_ps1) if v is not None)
+    return next(v for v in (fallback_step.get("ps1"), demo_ps1, global_ps1) if v is not None)
+
+
+def generate(config: dict, demos: list, output_path: str | Path) -> None:
+    """Generate a .cast file from config and demos.
+
+    Args:
+        config: dict with keys: width, height, title, ps1,
+                typing_delay, post_cmd_delay, between_demos{delay, clear},
+                comment_color
+        demos: list of {name, ps1?, steps} where each step is
+               {cmd, output?, ps1?}, {prompt, output?}, {pause}, or {comment, ps1?}
+        output_path: path to write the .cast file
+    """
+    width = config["width"]
+    height = config["height"]
+    title = config["title"]
+    global_ps1 = config["ps1"]
+    typing_delay = config["typing_delay"]
+    post_cmd_delay = config["post_cmd_delay"]
+    between_delay = config["between_demos"]["delay"]
+    between_clear = config["between_demos"]["clear"]
+    comment_color = config["comment_color"]
+
+    _validate(demos)
+
+    events = []
+    t = 0.0  # cumulative timestamp
+
+    def emit(text: str) -> None:
+        events.append([round(t, 6), "o", text])
+
+    for demo_idx, demo in enumerate(demos):
+        steps = demo["steps"]
+        demo_ps1 = demo.get("ps1")
+        prev_cmd_step: dict | None = None
+
+        # Demo-start PS1: find first cmd/comment step and emit its PS1
+        for step in steps:
+            if "cmd" in step or "comment" in step:
+                emit(next(v for v in (step.get("ps1"), demo_ps1, global_ps1) if v is not None))
+                break
+
+        for step_idx, step in enumerate(steps):
+            if "cmd" in step:
+                prev_cmd_step = step
+                for ch in step["cmd"]:
+                    t += typing_delay
+                    emit(ch)
+                emit("\r\n")
+                raw_output = (step.get("output", "") or "").replace("\\x1b", "\x1b")
+                lines = raw_output.rstrip("\n").splitlines()
+                next_step = steps[step_idx + 1] if step_idx + 1 < len(steps) else None
+                next_is_prompt = next_step is not None and "prompt" in next_step
+                for line_idx, line in enumerate(lines):
+                    is_last = line_idx == len(lines) - 1
+                    if is_last and next_is_prompt:
+                        emit(line)
+                    else:
+                        emit(line + "\r\n")
+                if not next_is_prompt:
+                    emit(_next_ps1(steps, step_idx + 1, demo_ps1, global_ps1, step))
+                t += post_cmd_delay
+
+            elif "prompt" in step:
+                for ch in step["prompt"]:
+                    t += typing_delay
+                    emit(ch)
+                emit("\r\n")
+                raw_output = (step.get("output", "") or "").replace("\\x1b", "\x1b")
+                lines = raw_output.rstrip("\n").splitlines()
+                for line in lines:
+                    emit(line + "\r\n")
+                fallback = prev_cmd_step if prev_cmd_step is not None else step
+                emit(_next_ps1(steps, step_idx + 1, demo_ps1, global_ps1, fallback))
+                t += post_cmd_delay
+
+            elif "pause" in step:
+                t += step["pause"]
+
+            elif "comment" in step:
+                text = "# " + step["comment"]
+                emit(comment_color)
+                for ch in text:
+                    t += typing_delay
+                    emit(ch)
+                emit("\x1b[0m")
+                emit("\r\n")
+                emit(_next_ps1(steps, step_idx + 1, demo_ps1, global_ps1, step))
+                t += post_cmd_delay
+
+            else:
+                keys = list(step.keys())
+                raise ValueError(
+                    f"Unrecognized step (keys: {keys}) in demo '{demo['name']}'. "
+                    f"Steps must have 'cmd', 'prompt', 'pause', or 'comment'."
+                )
+
+        if demo_idx < len(demos) - 1:
+            t += between_delay
+            if between_clear:
+                emit("\x1b[2J\x1b[H")
+
+    header = {
+        "version": 2,
+        "width": width,
+        "height": height,
+        "title": title,
+    }
+
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(json.dumps(header) + "\n")
+        for event in events:
+            f.write(json.dumps(event) + "\n")
+
+
+def main() -> None:
+    yaml_path = _HERE / "demo.yaml"
+    cast_path = _HERE / "demo.cast"
+
+    try:
+        with open(yaml_path, encoding="utf-8") as f:
+            script = yaml.safe_load(f)
+    except FileNotFoundError:
+        print(f"Error: demo script not found: {yaml_path}", file=sys.stderr)
+        sys.exit(1)
+    except yaml.YAMLError as e:
+        print(f"Error: failed to parse {yaml_path}: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    generate(script["config"], script["demos"], str(cast_path))
+    print(f"Written: {cast_path}")
+
+
+if __name__ == "__main__":
+    main()

demo/generate.py

@@ -36,4 +36,5 @@ dev = [
     "pyfiglet>=1.0.4",
     "pytest-cov>=4.0",
     "tox>=4.0",
+    "pyyaml>=6.0",
 ]