edgemint 0.1.0__tar.gz

edgemint-0.1.0/.claude/skills/edgemint/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: edgemint
+description: >
+  Generate style-faithful DOCX documents from Markdown using the edgemint CLI.
+  Use this skill when the user wants to: create a branded Word document from
+  Markdown or AsciiDoc, extract visual styles from a .docx template, regenerate
+  a document after editing its content, diff two style sheets, audit a template
+  change, or automate a batch document pipeline. Handles all edgemint commands:
+  extract-styles, extract, apply-styles, diff, validate, info, schema.
+argument-hint: "[template.docx] [action: extract|apply|diff|batch|inspect]"
+allowed-tools: Bash(edgemint *) Bash(pip install *) Bash(pandoc *) Read Write
+effort: high
+---
+
+# edgemint — DOCX Style Extraction & Document Generation
+
+You are an expert at producing style-faithful Word documents from Markdown
+source using the `edgemint` CLI. You understand DOCX named styles, Pandoc
+Extended Markdown `custom-style` annotations, and the three-file architecture
+(`content.md` + `styles.json` + `media/`).
+
+---
+
+## 0. Prerequisites Check
+
+Before any operation, verify edgemint is installed:
+
+```bash
+edgemint --version 2>/dev/null || echo "NOT_INSTALLED"
+```
+
+If `NOT_INSTALLED`:
+
+```bash
+pip install "edgemint[pandoc]"
+```
+
+Pandoc is required for `extract` and `apply-styles`. Confirm:
+
+```bash
+pandoc --version 2>/dev/null | head -1 || echo "PANDOC_MISSING"
+```
+
+---
+
+## 1. Core Concept
+
+edgemint separates **what a document looks like** from **what it says**:
+
+```
+  template.docx  ──extract-styles──►  styles.json   (visual identity)
+  content.md     ──apply-styles ──►   output.docx   (content + identity = output)
+```
+
+`styles.json` is the portable visual identity. Check it into version control.
+`content.md` is plain Pandoc Extended Markdown. Edit it freely.
+
+---
+
+## 2. Workflows
+
+### Workflow A — Extract styles from a template
+
+When the user has a `.docx` template and wants to understand or capture its styles:
+
+```bash
+edgemint extract-styles template.docx -o styles.json --resolved
+```
+
+Then read `styles.json` and summarise:
+- Total style count by type (paragraph / character / table)
+- Key custom styles (non-built-in, branded names)
+- Theme fonts (headings vs. body)
+- Color palette from theme
+
+Present a table: `name | type | font | size_pt | color`.
+
+---
+
+### Workflow B — Generate a styled document
+
+When the user wants to produce a branded `.docx` from Markdown content:
+
+1. If no `styles.json` exists yet, run Workflow A first.
+2. Read `styles.json` — note every available `name` value precisely.
+3. Write `content.md` using Pandoc Extended Markdown and `custom-style` annotations.
+4. Run `edgemint apply-styles content.md styles.json -o output.docx`.
+5. Confirm the output file exists and report its byte size.
+
+**Writing rules for `content.md`:**
+
+```markdown
+# Standard Markdown → auto-mapped to DOCX built-in styles
+
+# Heading 1          → Heading 1
+## Heading 2         → Heading 2
+
+Normal paragraph text → Normal / Body Text
+
+**bold**             → Strong character style
+*italic*             → Emphasis character style
+- Bullet item        → List Bullet
+1. Numbered item     → List Number
+> Blockquote         → Quote
+$E = mc^2$           → OMML equation (Pandoc converts LaTeX)
+![Cap](media/x.png)  → embedded image with media-dir lookup
+```
+
+```markdown
+# Named / branded styles → use custom-style annotations
+
+::: {custom-style="Heading 1"}
+Chapter Title
+:::
+
+::: {custom-style="Body Text"}
+Paragraph content.
+:::
+
+The project is [on track]{custom-style="Status Green"}.
+```
+
+**Rules:**
+1. **Always use the exact name from `styles.json`** — never guess or invent names.
+2. Prefer standard Markdown over `custom-style` when the auto-mapping is equivalent.
+3. Math: `$...$` inline, `$$...$$` display — Pandoc converts to OMML automatically.
+4. Images: `![Caption](media/file.png){width=80%}` — pass `--media` dir to `apply-styles`.
+5. Page breaks: raw OOXML fence:
+   ````
+   ```{=openxml}
+   <w:p><w:r><w:br w:type="page"/></w:r></w:p>
+   ```
+   ````
+
+---
+
+### Workflow C — Full round-trip extraction
+
+When the user wants to decompose an existing `.docx` into editable source:
+
+```bash
+edgemint extract document.docx -o project/
+```
+
+Produces:
+```
+project/
+  content.md    ← Pandoc Extended Markdown (all content)
+  styles.json   ← complete visual identity
+  media/        ← all embedded images, extracted
+```
+
+Explain the structure, then tell the user how to re-generate:
+
+```bash
+edgemint apply-styles project/content.md project/styles.json \
+  -o rebuilt.docx --media project/media
+```
+
+---
+
+### Workflow D — Diff / audit styles
+
+When the user wants to compare two templates or detect brand changes:
+
+```bash
+edgemint extract-styles old-template.docx -o before.json
+edgemint extract-styles new-template.docx -o after.json
+edgemint diff before.json after.json
+```
+
+Present the diff grouped by: **Added**, **Removed**, **Modified** (with exact
+property changes).
+
+---
+
+### Workflow E — Batch document generation
+
+When the user wants to generate multiple documents from one template:
+
+```bash
+edgemint extract-styles template.docx -o styles.json  # once
+
+for md in docs/*.md; do
+  name=$(basename "$md" .md)
+  edgemint apply-styles "$md" styles.json -o "output/${name}.docx"
+done
+```
+
+Write each `.md` file with proper `custom-style` annotations before running the
+loop. Show the user the file count and total output size when done.
+
+---
+
+### Workflow F — Quick inspection
+
+```bash
+edgemint info document.docx
+```
+
+Summarise: style count, key custom styles, paragraph vs. character split.
+
+---
+
+## 3. Error Handling
+
+| Exit code | Meaning | Action |
+|-----------|---------|--------|
+| 0 | Success | Continue |
+| 1 | Usage error | Show correct usage |
+| 2 | File not found / invalid | Check path, check it's a valid DOCX |
+| 3 | Schema / validation error | Run `edgemint validate styles.json` |
+| 4 | Pandoc error | Run `pandoc --version`; install `edgemint[pandoc]` if missing |
+| 5 | Security error | Warn user — file failed ZIP bomb / path traversal check |
+
+Warnings about "style deduplication" and "list style" are normal — edgemint
+auto-fixes both (Pandoc bugs #7280 / #8350). Do not flag them to the user.
+
+---
+
+## 4. Output Confirmation
+
+After every `apply-styles` call:
+
+```bash
+ls -lh output.docx
+```
+
+Report: `✓ output.docx (42 KB)` or the equivalent.
+
+---
+
+## 5. Principles
+
+- Never modify `styles.json` manually — always re-extract from the source `.docx`.
+- Never invent style names — only use names that appear in `styles.json`.
+- The three-file architecture (`content.md` + `styles.json` + `media/`) maps to
+  a natural Git repo layout: content and identity evolve independently.
+- When in doubt, run `edgemint validate styles.json` before generating.

edgemint-0.1.0/.claude/skills/edgemint-packt/SKILL.md

@@ -0,0 +1,381 @@
+---
+name: edgemint-packt
+description: >
+  Write and generate Packt publisher manuscripts as pixel-perfect DOCX using
+  edgemint. Use this skill when the user is authoring a Packt book chapter,
+  applying Packt house styles, generating or reviewing a Packt-style Word
+  document, or converting Markdown to a Packt-compliant manuscript. Knows every
+  Packt paragraph style, character style, callout, list level, and code block
+  variant. Triggers on: "Packt chapter", "Packt style", "publisher manuscript",
+  "Packt template", "write a chapter for Packt", "generate Packt DOCX".
+argument-hint: "[chapter.md | template.docx] [action: write|generate|extract|review]"
+allowed-tools: Bash(edgemint *) Bash(pip install *) Bash(pandoc *) Read Write
+effort: high
+---
+
+# edgemint — Packt Publisher House Style
+
+You are an expert Packt technical author and DOCX production engineer. You
+write chapter Markdown with precise Packt `custom-style` annotations and
+generate pixel-perfect Packt manuscripts using `edgemint`.
+
+---
+
+## 0. Prerequisites
+
+```bash
+edgemint --version 2>/dev/null || pip install "edgemint[pandoc]"
+```
+
+If the user has the Packt Word template (`.docx`), extract the style catalogue:
+
+```bash
+edgemint extract-styles packt-template.docx -o packt.json --resolved
+edgemint validate packt.json
+```
+
+If no template is available, use the embedded style catalogue in Section 2 of
+this skill — all style names are known and stable across Packt templates.
+
+---
+
+## 1. Packt Authoring Workflow
+
+```
+content.md  ──►  edgemint apply-styles content.md packt.json -o chapter.docx
+```
+
+The complete authoring loop:
+
+1. **Extract** styles from the Packt `.docx` template (once per project).
+2. **Write** chapter Markdown using the style catalogue below.
+3. **Generate** `chapter.docx` with one command.
+4. **Review** only the Word output — never edit the `.docx` directly.
+5. **Iterate** in `content.md` until the chapter is approved.
+
+---
+
+## 2. Complete Packt Style Catalogue
+
+These are the canonical Packt named styles. Use **exact** names.
+
+### Chapter openers
+
+```markdown
+::: {custom-style="HS - ChapterNumber"}
+Chapter 3
+:::
+
+::: {custom-style="HS - ChapterTitle"}
+Understanding Transformer Architectures
+:::
+```
+
+| Style | Purpose |
+|-------|--------|
+| `HS - ChapterNumber` | "Chapter N" label at chapter top |
+| `HS - ChapterTitle` | Chapter title text |
+| `HS - Heading 1` | Major section header |
+| `HS - Heading 2` | Sub-section header |
+| `HS - Heading 3` | Sub-sub-section header |
+| `HS - Heading 4` | Lowest heading level |
+
+### Body text
+
+| Style | Purpose |
+|-------|--------|
+| `P0 - Paragraph` | Primary Packt body paragraph (use after callouts and headings) |
+| `P0 - ParagraphCenter` | Centred paragraph (epigraphs, visual breaks) |
+| `P1 - Paragraph` | Secondary body paragraph (lighter typographic weight) |
+
+### Callout boxes
+
+```markdown
+::: {custom-style="I - InfoBox"}
+**Tip header.** Body of the callout. Keep it to three sentences or fewer.
+:::
+
+::: {custom-style="T - TipBox"}
+**Tip.** This tip should change one concrete decision. If it doesn't, cut it.
+:::
+
+::: {custom-style="C - Citation"}
+"A production ML pipeline fails first at the seam between intention and
+repeatability."
+:::
+```
+
+| Style | Purpose |
+|-------|--------|
+| `I - InfoBox` | Background information callout |
+| `T - TipBox` | Actionable tip (must suggest a concrete action) |
+| `C - Citation` | Block quotation |
+| `QS - Quote` | Standalone pull-quote |
+
+### Code listings
+
+```markdown
+::: {custom-style="C0 - CodeBlock"}
+def train_step(model, batch):
+    logits = model(batch["input_ids"])
+    return loss_fn(logits, batch["labels"])
+:::
+
+::: {custom-style="C0 - ConsoleBlock"}
+$ python train.py --epochs 10 --lr 1e-4
+Epoch 1/10: loss=2.34
+:::
+```
+
+| Style | Purpose |
+|-------|--------|
+| `C0 - CodeBlock` | Primary code listing (Python, YAML, JSON, etc.) |
+| `C0 - ConsoleBlock` | Terminal / shell session output |
+| `C1 - CodeBlock` | Secondary code listing (alternative for contrast) |
+| `C1 - ConsoleBlock` | Secondary console output |
+
+> **Rule:** never use fenced code blocks (` ``` `) in Packt manuscripts. Always
+> use the `custom-style` div form above so the correct Packt monospace font applies.
+
+### Lists
+
+Use native Markdown lists whenever the auto-mapping is sufficient. For
+explicit Packt list styles:
+
+```markdown
+::: {custom-style="L1 - Bullet"}
+Level 1 bullet item.
+:::
+
+::: {custom-style="L2 - Bullet"}
+Nested level 2 bullet.
+:::
+
+::: {custom-style="L1 - Numbered"}
+First numbered step.
+:::
+
+::: {custom-style="L2 - Numbered"}
+Nested numbered sub-step.
+:::
+```
+
+Full list style catalogue:
+
+| Style | Purpose |
+|-------|--------|
+| `L1 - Bullet` / `L2 - Bullet` / `L3 - Bullet` | Bullet list levels 1–3 |
+| `L1 - Numbered` / `L2 - Numbered` / `L3 - Numbered` | Numbered list levels 1–3 |
+| `L1 - Alphabet` / `L2 - Alphabet` / `L3 - Alphabet` | Alphabetic list levels 1–3 |
+
+### Figures and captions
+
+```markdown
+![Transformer self-attention mechanism](media/fig-3-1.png){ width=80% }
+
+::: {custom-style="F0 - FigureCaption"}
+Figure 3.1 — Self-attention scores for a single head across 512 token
+positions. The diagonal shows each token attending primarily to itself during
+   early training.
+:::
+```
+
+| Style | Purpose |
+|-------|--------|
+| `F0 - Figure` | Figure container paragraph |
+| `F0 - FigureCaption` | Caption immediately below figure |
+
+Always store images in `media/` and pass `--media media` when generating:
+
+```bash
+edgemint apply-styles chapter.md packt.json -o chapter.docx --media media
+```
+
+### Tables
+
+Wrap tables in the `TS - Table` style:
+
+```markdown
+::: {custom-style="TS - Table"}
+| Header A         | Header B              | Header C          |
+|:-----------------|:----------------------|:------------------|
+| Row 1 cell       | Row 1 cell            | Row 1 cell        |
+| Row 2 cell       | Row 2 cell            | Row 2 cell        |
+:::
+```
+
+| Style | Purpose |
+|-------|--------|
+| `TS - Table` | Outer table wrapper |
+| `TS - TableBullet` | Bullet item inside a table cell |
+| `TS - TableCenter` | Centred text in a table cell |
+| `TS - TableNumberedList` | Numbered item inside a table cell |
+
+---
+
+## 3. Inline Character Styles
+
+Apply within paragraph text using the bracketed span syntax:
+
+```markdown
+The [transformer]{custom-style="CS - Keyword"} model calls
+[self_attention()]{custom-style="CS - InlineCode"} to compute scores.
+```
+
+| Style | Use for |
+|-------|--------|
+| `CS - Keyword` | Technical terms, model names, product names |
+| `CS - InlineCode` | Code identifiers, function names, CLI flags |
+| `CS - BoldItalic` | Strong combined emphasis (use sparingly) |
+| `CS - Italic` | Editorial asides, first-use definitions |
+| `CS - URL` | Hyperlinks (alternative to standard Markdown link syntax) |
+| `CS - Screentext` | UI labels, menu items, button names |
+| `CS - Subscript` | Chemical formulae, math subscripts |
+| `CS - Superscript` | Footnote anchors, math superscripts |
+
+---
+
+## 4. Complete Chapter Template
+
+Use this as the starting structure for every new Packt chapter:
+
+```markdown
+---
+title: "Chapter N: Chapter Title"
+author: "Author Name"
+---
+
+::: {custom-style="HS - ChapterNumber"}
+Chapter N
+:::
+
+::: {custom-style="HS - ChapterTitle"}
+Chapter Title
+:::
+
+::: {custom-style="P0 - Paragraph"}
+Opening paragraph of the chapter — sets the scene and provides a concrete
+problem statement. Keep to 3–5 sentences.
+:::
+
+# Section Heading
+
+::: {custom-style="P0 - Paragraph"}
+First paragraph of a new section. Use P0 after headings.
+:::
+
+Body text that continues directly uses standard Markdown paragraphs, which
+map to the Normal style automatically.
+
+## Sub-section Heading
+
+::: {custom-style="I - InfoBox"}
+**Important.** Add critical context here that a reader must have before
+proceeding. One or two sentences.
+:::
+
+### Code Example
+
+::: {custom-style="C0 - ConsoleBlock"}
+$ python --version
+Python 3.12.0
+:::
+
+::: {custom-style="C0 - CodeBlock"}
+import torch
+
+model = TransformerModel(vocab_size=50257, d_model=768)
+output = model(input_ids)
+:::
+
+::: {custom-style="P0 - Paragraph"}
+The paragraph immediately following a code listing explains what the code does.
+Never leave code blocks without explanatory text.
+:::
+
+# Summary
+
+::: {custom-style="P0 - Paragraph"}
+Summary paragraph. Bullet the three key takeaways of the chapter below.
+:::
+
+- First key takeaway.
+- Second key takeaway.
+- Third key takeaway.
+```
+
+---
+
+## 5. Packt House Rules
+
+Follow these rules when writing content:
+
+1. **No orphan code blocks** — every code listing must be preceded and followed by explanatory prose.
+2. **InfoBox / TipBox sparingly** — maximum one callout per sub-section.
+3. **Figure captions are mandatory** — never include a figure without an `F0 - FigureCaption`.
+4. **Chapter number in `HS - ChapterNumber`** — this is separate from the title.
+5. **P0 after headings** — always use `P0 - Paragraph` for the first paragraph after a heading.
+6. **Avoid passive voice** in code comments and captions.
+7. **Code in console blocks uses `$` prompt** — never use `>>>` for shell commands.
+8. **All URLs are hyperlinks** — use `[text](url)` or `{custom-style="CS - URL"}`.
+9. **Figure numbering** — `Figure N.M — Description.` (chapter number dot figure number, em dash).
+10. **Table caption** — place above the table using a plain paragraph: `*Table N.M — Description.*`
+
+---
+
+## 6. Generating the Manuscript
+
+```bash
+# Single chapter
+edgemint apply-styles chapter-03.md packt.json -o chapter-03.docx --media media
+
+# All chapters in a book
+for md in chapters/chapter-*.md; do
+  base=$(basename "$md" .md)
+  edgemint apply-styles "$md" packt.json -o "output/${base}.docx" --media media
+done
+ls -lh output/
+```
+
+After generation, confirm:
+
+```bash
+edgemint info output/chapter-03.docx
+# Shows style count — verify it matches your template
+```
+
+---
+
+## 7. Validating the Style Sheet
+
+```bash
+edgemint validate packt.json     # → Valid (exit 0)
+
+# List all available Packt style names
+python3 -c "
+import json
+for s in json.load(open('packt.json'))['styles']:
+    print(f\"{s['type']:15} {s['name']}\")
+" | sort
+```
+
+---
+
+## 8. Error Handling
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Style not applying | Wrong style name (typo or case) | Check exact name in`packt.json` |
+| Images missing | `--media` not passed | Add `--media media` to the command |
+| Font looks wrong | Font not embedded in template | Re-extract from the original `.docx` |
+| `exit 4` | Pandoc missing | `pip install "edgemint[pandoc]"` |
+| `exit 5` | Security error | File failed ZIP inspection — use a clean template |
+
+---
+
+## 9. Further Reading
+
+- [Packt Author Guide](docs/packt-author-guide.md) — complete human-readable authoring guide
+- [edgemint Skill](.claude/skills/edgemint/SKILL.md) — general (non-Packt) document generation
+- [Style Guide](docs/style-guide.md) — `custom-style` annotation reference
+- [CLI Reference](docs/cli-reference.md) — all commands and flags

edgemint-0.1.0/.dockerignore

@@ -0,0 +1,20 @@
+.venv/
+.git/
+.github/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.coverage
+coverage.xml
+htmlcov/
+tests/
+docs/
+specs/
+examples/
+.DS_Store
+*.docx
+*.tmp