create-dokio 0.1.9 → 0.1.11

package/README.md

@@ -1,6 +1,6 @@
 # create-dokio
 
-CLI scaffold for Dokio templates. Generates the correct file structure, `data.yaml`, HTML boilerplate, and SCSS partials for PDF, General, Email, and Video template types.
+CLI scaffold for Dokio hub repos and templates. Generates correct file structure, `data.yaml`, HTML boilerplate, SCSS partials, and auto-wires changelog tooling.
 
 ## Usage
 
@@ -14,6 +14,77 @@ npx create-dokio pool-care
 
 > Using pnpm? `pnpm dlx create-dokio`
 
+Run from your **repos workspace folder** — the folder where all your hub repos live (e.g. `~/Projects/dokio/`).
+
+---
+
+## Commands
+
+### `create-dokio hub`
+
+Creates a new hub repository locally with full structure ready to push.
+
+```bash
+npx create-dokio hub
+```
+
+**Prompts:**
+- Hub ID (kebab-case, e.g. `bupa-sam`)
+- Hub display name (e.g. `Bupa Sales And Marketing Hub`)
+
+**Generates:**
+
+```
+bupa-sam-templates/
+├── .githooks/
+│   ├── commit-msg        # Enforces conventional commits
+│   └── post-commit       # Auto-updates template CHANGELOGs on commit
+├── .vscode/
+│   └── settings.json     # scss.validate: false, css.validate: false
+├── templates/            # All templates live here
+├── tools/
+│   └── changelog/
+│       ├── update_changelog.py   # Changelog generator script
+│       └── .env.example          # ANTHROPIC_API_KEY for AI descriptions
+├── .gitignore
+└── README.md
+```
+
+**Next steps after hub creation:**
+
+```bash
+cd bupa-sam-templates
+# Create GitHub repo at github.com/dokioco/bupa-sam-templates
+git remote add origin https://github.com/dokioco/bupa-sam-templates
+git push -u origin main
+
+# Optional — enable AI changelog descriptions:
+cp tools/changelog/.env.example tools/changelog/.env
+# Add your ANTHROPIC_API_KEY to tools/changelog/.env
+```
+
+---
+
+### `create-dokio template`
+
+Scaffolds a new template inside an existing hub repo. Clones the hub if not found locally.
+
+```bash
+npx create-dokio template
+# or just:
+npx create-dokio
+```
+
+**Prompts:**
+- Template ID (e.g. `HW485`)
+- Template name (e.g. `My Cool Template`)
+- Template type (PDF / General / Email / Video)
+- Hub selection
+
+If the hub repo exists locally, it pulls latest. If not, it clones it.
+
+If the hub is missing any tooling (changelog script, hooks, `.vscode`, `.gitignore`, `README.md`), it adds them automatically.
+
 ---
 
 ## Template types
@@ -22,15 +93,14 @@ npx create-dokio pool-care
 PrinceXML-rendered print documents. Supports multi-page, resizable layouts, orderable exports, and proof downloads.
 
 ```
-dokio-pool-care/
+HW485-my-cool-template/
 ├── CHANGELOG.md
 ├── data.yaml
 ├── index.html
 ├── assets/
 ├── partials/
 │   ├── page1-cover.html
-│   ├── page2-content.html
-│   └── page3-cta.html
+│   └── page2-content.html
 └── scss/
     ├── style.scss.hbs
     ├── _fonts.scss
@@ -38,35 +108,24 @@ dokio-pool-care/
     ├── _variables.scss
     └── pages/
         ├── _page1.scss
-        ├── _page2.scss
-        └── _page3.scss
+        └── _page2.scss
 ```
 
-**Prompts:**
-- Page dimensions (mm)
-- Page count
-- PrinceXML version (11 or 15 — use 15 for flexbox)
-- Resizable template
-- Proof downloads (`draft_proofable`)
-- Orderable export (Print from Snap)
+**Prompts:** page dimensions (mm), page count, PrinceXML version (11 or 15), resizable, proof downloads, orderable export.
 
 ---
 
 ### General (image)
 Chrome-rendered image output — JPG and/or PNG. Single or multi-section layouts.
 
-**Prompts:**
-- Dimensions (px)
-- Page/section count
-- Export formats (JPG, PNG, or both)
+**Prompts:** dimensions (px), page/section count, export formats (JPG, PNG, or both).
 
 ---
 
 ### Email
 HTML email scaffold. Includes Outlook conditional comments, `{{{___assembled_css}}}` injection, `{{{subject}}}` title, and Gmail-safe table structure.
 
-**Prompts:**
-- Subdomain only — email structure is fixed at 600px
+**Prompts:** subdomain only — email structure is fixed at 600px.
 
 ---
 
@@ -75,36 +134,34 @@ HTML email scaffold. Includes Outlook conditional comments, `{{{___assembled_css
 
 ---
 
-## What gets generated
-
-| File | Description |
-|---|---|
-| `data.yaml` | Dokio template config — set your template ID and subdomain before upload |
-| `index.html` | Entry HTML with Handlebars partial includes |
-| `partials/*.html` | Per-page/section HTML fragments |
-| `scss/style.scss.hbs` | Main SCSS entry — supports Handlebars syntax |
-| `scss/_fonts.scss` | Empty with commented `@font-face` example |
-| `scss/_variables.scss` | Dimension, colour, and typography variables |
-| `scss/_mixins.scss` | `absolute()`, `flex()`, `truncate()` mixins |
-| `scss/pages/_pageN.scss` | Per-page style partials |
-| `assets/` | Drop fonts, images, and local assets here |
-| `CHANGELOG.md` | Template-level changelog |
+## Changelog generator
+
+Each template has its own `CHANGELOG.md`. After every commit that touches a template folder, the `post-commit` hook automatically:
+
+1. Detects which templates changed
+2. Logs the commit to each affected template's `CHANGELOG.md` (author, date, branch, title, files with status labels)
+3. Amends the commit silently to include the changelog update
+
+**Description generation:**
+- If `tools/changelog/.env` exists with a valid `ANTHROPIC_API_KEY` → Claude Haiku generates a description
+- If no key → falls back to `TODO - INTEGRATE WITH AI (JAKE TASK)`
 
 ---
 
-## After scaffolding
+## After scaffolding a template
 
 ```bash
-cd dokio-<name>
-
-# 1. Set your template ID in data.yaml
-#    name: TEMPLATEID - dokio-<name>  ← replace TEMPLATEID
+cd bupa-sam-templates/templates/HW485-my-cool-template
 
-# 2. Change subdomain from 'test' before uploading
-#    subdomain: your-hub-subdomain
+# 1. Check data.yaml — name and subdomain are auto-set
+# 2. Add assets to assets/
+# 3. Edit partials/
 
-# 3. Add fonts/images to assets/
-#    Declare fonts in scss/_fonts.scss
+# When ready to commit (from hub root):
+cd ../../
+git add templates/HW485-my-cool-template/
+git commit -m "feat: add My Cool Template"
+git push
 ```
 
 ---
@@ -112,23 +169,28 @@ cd dokio-<name>
 ## Development
 
 ```bash
-git clone <repo>
+git clone https://github.com/dokioco/create-dokio
+cd create-dokio
 pnpm install
-pnpm dev       # watch mode
-pnpm build     # compile to dist/
+pnpm build       # compile to dist/
+pnpm link --global
 ```
 
 ### Commit format
 
-This repo uses [Conventional Commits](https://www.conventionalcommits.org/):
+Enforced by commitlint on every commit:
 
 ```
 feat: add resizable PDF option
 fix: correct page count in data.yaml
 chore: update dependencies
+docs: update README
 ```
 
-`CHANGELOG.md` updates automatically on `git push`.
+Breaking changes:
+```
+feat!: redesign template API
+```
 
 ---
 

package/dist/index.js

@@ -881,6 +881,219 @@ import { join, basename } from "path";
 import { execSync } from "child_process";
 import fse from "fs-extra";
 import kleur2 from "kleur";
+
+// src/templates/changelog.ts
+function changelogScript() {
+  return `#!/usr/bin/env python3
+"""Prepend a new entry into a template's CHANGELOG.md."""
+import sys
+import re
+import os
+import datetime
+
+
+def load_dotenv():
+    env_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), ".env")
+    if not os.path.isfile(env_path):
+        return
+    with open(env_path) as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, _, val = line.partition("=")
+            key = key.strip()
+            val = val.strip().strip('"').strip("'")
+            if key and key not in os.environ:
+                os.environ[key] = val
+
+
+load_dotenv()
+
+
+STATUS_LABELS = {
+    "A": "Added",
+    "M": "Modified",
+    "D": "Deleted",
+    "R": "Renamed",
+    "C": "Copied",
+}
+
+
+def format_date(today_str):
+    d = datetime.datetime.strptime(today_str, "%Y-%m-%d")
+    day = str(int(d.strftime("%d")))
+    return d.strftime(f"%B {day}, %Y")
+
+
+def generate_description(title, files, diff):
+    try:
+        import anthropic
+    except ImportError:
+        return None
+
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        return None
+
+    try:
+        client = anthropic.Anthropic(api_key=api_key)
+        files_str = "\\n".join(f"- {label}: {path}" for label, path in files)
+        diff_section = f"\\n\\nDiff:\\n\`\`\`\\n{diff[:4000]}\\n\`\`\`" if diff.strip() else ""
+
+        prompt = (
+            f"You are writing a changelog description for a Dokio template.\\n\\n"
+            f"Commit title: {title}\\n"
+            f"Files changed:\\n{files_str}"
+            f"{diff_section}\\n\\n"
+            f"Write a clear, concise description (2-4 sentences) explaining what changed and why. "
+            f"Focus on impact and purpose. Be specific but brief. No markdown headers or bullet points."
+        )
+
+        message = client.messages.create(
+            model="claude-haiku-4-5-20251001",
+            max_tokens=256,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return message.content[0].text.strip()
+    except Exception:
+        return None
+
+
+def parse_files(files_raw, template_prefix):
+    files = []
+    for line in files_raw.strip().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        parts = line.split("\\t")
+        if len(parts) >= 2:
+            status_key = parts[0].strip()[0].upper()
+            label = STATUS_LABELS.get(status_key, "Modified")
+            path = parts[-1].strip()
+        else:
+            label = "Modified"
+            path = parts[0].strip()
+        if template_prefix and path.startswith(template_prefix + "/"):
+            path = path[len(template_prefix):].lstrip("/")
+        files.append((label, path))
+    return files
+
+
+def build_entry_content(branch, title, description, author, today_str, files):
+    date_str = format_date(today_str)
+    lines = [
+        f"**{author}** \u2022 *{date_str}*",
+        f"**branch:** \`{branch}\`",
+        "",
+        f"**title:** {title}",
+        "",
+        f"**description:** {description}",
+        "",
+        "### Files Changed",
+    ]
+    for label, path in files:
+        lines.append(f"- **{label}** \`{path}\`")
+    return "\\n".join(lines)
+
+
+def update_changelog(path, branch, today, title, author, files, diff):
+    with open(path, "r") as f:
+        content = f.read()
+
+    description = generate_description(title, files, diff) or "TODO - INTEGRATE WITH AI (JAKE TASK)"
+    entry_content = build_entry_content(branch, title, description, author, today, files)
+
+    insert_match = re.search(r"^(---|## )", content, re.MULTILINE)
+
+    if insert_match:
+        insert_pos = insert_match.start()
+        if content[insert_pos:].startswith("---"):
+            new_block = f"---\\n\\n{entry_content}\\n\\n"
+        else:
+            new_block = f"---\\n\\n{entry_content}\\n\\n---\\n\\n"
+        content = content[:insert_pos] + new_block + content[insert_pos:]
+    else:
+        content = content.rstrip("\\n") + f"\\n\\n---\\n\\n{entry_content}\\n\\n---\\n"
+
+    with open(path, "w") as f:
+        f.write(content)
+
+
+if __name__ == "__main__":
+    path = sys.argv[1]
+    today = sys.argv[2]
+    branch = os.environ.get("CHANGELOG_BRANCH", "")
+    message = os.environ.get("CHANGELOG_MESSAGE", "")
+    author = os.environ.get("CHANGELOG_AUTHOR", "")
+    files_raw = os.environ.get("CHANGELOG_FILES", "")
+    template_prefix = os.environ.get("CHANGELOG_TEMPLATE_PREFIX", "")
+    diff = os.environ.get("CHANGELOG_DIFF", "")
+
+    files = parse_files(files_raw, template_prefix)
+    update_changelog(path, branch, today, message, author, files, diff)
+`;
+}
+function changelogHook() {
+  return `#!/bin/bash
+# Auto-updates CHANGELOG.md in modified template folders after each commit.
+# Amends the commit silently to include changelog changes.
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+LOCK="$REPO_ROOT/.git/changelog-hook-running"
+
+[ -f "$LOCK" ] && exit 0
+
+CHANGED=$(git diff-tree --no-commit-id -r --name-only HEAD | grep -v "CHANGELOG\\.md$")
+[ -z "$CHANGED" ] && exit 0
+
+# Detect changed templates (expects templates/<template-id>/ structure)
+TEMPLATES=$(echo "$CHANGED" | grep "^templates/" | awk -F'/' '{print $1"/"$2}' | sort -u)
+[ -z "$TEMPLATES" ] && exit 0
+
+COMMIT_MSG=$(git log -1 --pretty=%s)
+AUTHOR=$(git log -1 --pretty="%an")
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+TODAY=$(date +%Y-%m-%d)
+
+touch "$LOCK"
+trap 'rm -f "$LOCK"' EXIT
+
+AMENDED=0
+while IFS= read -r TEMPLATE; do
+  [ -z "$TEMPLATE" ] && continue
+  CHANGELOG="$REPO_ROOT/$TEMPLATE/CHANGELOG.md"
+  [ ! -f "$CHANGELOG" ] && continue
+
+  TEMPLATE_FILES=$(git diff-tree --no-commit-id -r --name-status HEAD \\
+    | grep -v "CHANGELOG\\.md$" \\
+    | grep -E $'\\t'"$TEMPLATE/")
+
+  TEMPLATE_DIFF=$(git diff-tree --no-commit-id -r -p HEAD -- "$TEMPLATE/" 2>/dev/null | head -c 4000)
+
+  export CHANGELOG_BRANCH="$BRANCH"
+  export CHANGELOG_MESSAGE="$COMMIT_MSG"
+  export CHANGELOG_AUTHOR="$AUTHOR"
+  export CHANGELOG_FILES="$TEMPLATE_FILES"
+  export CHANGELOG_TEMPLATE_PREFIX="$TEMPLATE"
+  export CHANGELOG_DIFF="$TEMPLATE_DIFF"
+  python3 "$REPO_ROOT/tools/changelog/update_changelog.py" "$CHANGELOG" "$TODAY"
+
+  git add "$CHANGELOG"
+  AMENDED=1
+done <<< "$TEMPLATES"
+
+if [ "$AMENDED" = "1" ]; then
+  git commit --amend --no-edit
+fi
+`;
+}
+function changelogEnvExample() {
+  return `ANTHROPIC_API_KEY=sk-ant-...
+`;
+}
+
+// src/git.ts
 async function ensureHubRepo(hubId) {
   const cwd = process.cwd();
   const dirName = hubRepoDirName(hubId);
@@ -898,13 +1111,61 @@ async function ensureHubRepo(hubId) {
   return hubDir;
 }
 async function setupHooks(hubDir) {
-  const hookPath = join(hubDir, ".githooks", "commit-msg");
-  if (!await fse.pathExists(hookPath)) {
-    await fse.ensureDir(join(hookPath, ".."));
-    await fse.writeFile(hookPath, commitMsgHook(), "utf8");
-    await fse.chmod(hookPath, 493);
+  const commitMsgPath = join(hubDir, ".githooks", "commit-msg");
+  if (!await fse.pathExists(commitMsgPath)) {
+    await fse.ensureDir(join(commitMsgPath, ".."));
+    await fse.writeFile(commitMsgPath, commitMsgHook(), "utf8");
+    await fse.chmod(commitMsgPath, 493);
     console.log(kleur2.dim(`  + .githooks/commit-msg`));
   }
+  const postCommitPath = join(hubDir, ".githooks", "post-commit");
+  const changelogScriptPath = join(hubDir, "tools", "changelog", "update_changelog.py");
+  if (!await fse.pathExists(changelogScriptPath)) {
+    await fse.ensureDir(join(changelogScriptPath, ".."));
+    await fse.writeFile(changelogScriptPath, changelogScript(), "utf8");
+    await fse.chmod(changelogScriptPath, 493);
+    console.log(kleur2.dim(`  + tools/changelog/update_changelog.py`));
+    const envExamplePath = join(hubDir, "tools", "changelog", ".env.example");
+    await fse.writeFile(envExamplePath, changelogEnvExample(), "utf8");
+    console.log(kleur2.dim(`  + tools/changelog/.env.example`));
+    if (!await fse.pathExists(postCommitPath)) {
+      await fse.writeFile(postCommitPath, changelogHook(), "utf8");
+      await fse.chmod(postCommitPath, 493);
+      console.log(kleur2.dim(`  + .githooks/post-commit`));
+    }
+  }
+  const vscodePath = join(hubDir, ".vscode", "settings.json");
+  if (!await fse.pathExists(vscodePath)) {
+    await fse.ensureDir(join(vscodePath, ".."));
+    await fse.writeFile(vscodePath, JSON.stringify({ "scss.validate": false, "css.validate": false }, null, 2) + "\n", "utf8");
+    console.log(kleur2.dim(`  + .vscode/settings.json`));
+  }
+  const gitignorePath = join(hubDir, ".gitignore");
+  const requiredIgnores = [".DS_Store", "node_modules/", "*.log", "tools/changelog/.env"];
+  if (!await fse.pathExists(gitignorePath)) {
+    await fse.writeFile(gitignorePath, requiredIgnores.join("\n") + "\n", "utf8");
+    console.log(kleur2.dim(`  + .gitignore`));
+  } else {
+    const existing = await fse.readFile(gitignorePath, "utf8");
+    const missing = requiredIgnores.filter((e) => !existing.includes(e));
+    if (missing.length) {
+      await fse.appendFile(gitignorePath, missing.join("\n") + "\n");
+      console.log(kleur2.dim(`  ~ .gitignore (added: ${missing.join(", ")})`));
+    }
+  }
+  const readmePath = join(hubDir, "README.md");
+  if (!await fse.pathExists(readmePath)) {
+    const hubName = basename(hubDir);
+    await fse.writeFile(readmePath, `# ${hubName}
+
+Templates for ${hubName} on Dokio.
+
+## Creating a new template
+
+Run \`create-dokio template\` from inside this repo.
+`, "utf8");
+    console.log(kleur2.dim(`  + README.md`));
+  }
   execSync("git config core.hooksPath .githooks", { cwd: hubDir, stdio: "ignore" });
 }
 
@@ -1000,12 +1261,15 @@ async function runHub() {
   }
   const files = {
     ".githooks/commit-msg": commitMsgHook(),
+    ".githooks/post-commit": changelogHook(),
     ".vscode/settings.json": JSON.stringify({ "scss.validate": false, "css.validate": false }, null, 2) + "\n",
     "templates/.gitkeep": "",
-    "tools/.gitkeep": "",
+    "tools/changelog/update_changelog.py": changelogScript(),
+    "tools/changelog/.env.example": changelogEnvExample(),
     ".gitignore": `.DS_Store
 node_modules/
 *.log
+tools/changelog/.env
 `,
     "README.md": `# ${hubName}
 
@@ -1021,7 +1285,7 @@ Run \`create-dokio template\` from inside this repo.
     const fullPath = join4(outDir, rel);
     await fse4.ensureDir(join4(fullPath, ".."));
     await fse4.writeFile(fullPath, content, "utf8");
-    if (rel === ".githooks/commit-msg") await fse4.chmod(fullPath, 493);
+    if (rel === ".githooks/commit-msg" || rel === ".githooks/post-commit" || rel === "tools/changelog/update_changelog.py") await fse4.chmod(fullPath, 493);
     console.log(kleur5.dim(`  + ${rel}`));
   }
   execSync2("git init", { cwd: outDir, stdio: "ignore" });
@@ -1037,6 +1301,10 @@ Run \`create-dokio template\` from inside this repo.
   console.log(kleur5.dim(`    git remote add origin https://github.com/dokioco/${dirName}`));
   console.log(kleur5.dim(`    git push -u origin main`));
   console.log("");
+  console.log(kleur5.dim(`  Changelog (optional \u2014 for AI descriptions):`));
+  console.log(kleur5.dim(`    cp tools/changelog/.env.example tools/changelog/.env`));
+  console.log(kleur5.dim(`    # Add your ANTHROPIC_API_KEY to tools/changelog/.env`));
+  console.log("");
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dokio",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "CLI scaffold for Dokio templates",
   "type": "module",
   "bin": {
@@ -21,14 +21,17 @@
     "@commitlint/cli": "^19.0.0",
     "@commitlint/config-conventional": "^19.0.0",
     "@commitlint/types": "^19.0.0",
+    "@eslint/js": "^10.0.1",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^20.0.0",
     "@types/prompts": "^2.4.9",
     "changelogen": "^0.6.2",
+    "eslint": "^10.4.1",
     "husky": "^9.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.22.3",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "typescript-eslint": "^8.60.0"
   },
   "tsup": {
     "entry": {
@@ -52,6 +55,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "changelog": "changelogen --bump && tsx scripts/changelog.ts"
+    "lint": "eslint",
+    "changelog": "changelogen --bump && tsx scripts/changelog.ts",
+    "release": "changelogen --bump --output CHANGELOG.md && git add package.json CHANGELOG.md && git commit -m \"chore(release): v$(node -p 'require(\"./package.json\").version')\" && git push -u origin HEAD"
   }
 }