Metadata-Version: 2.4
Name: edgemint
Version: 1.2.1
Summary: DOCX style extraction and regeneration CLI
Author: Raphael Mansuy
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: lxml>=5.2.0
Requires-Dist: pydantic<3,>=2.8.0
Requires-Dist: python-docx>=1.2.0
Requires-Dist: typer<1,>=0.12.3
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.11.0; extra == 'dev'
Provides-Extra: pandoc
Requires-Dist: pypandoc-binary>=1.15; extra == 'pandoc'
Description-Content-Type: text/markdown

# edgemint

![edgemint hero](./assets/01-hero.jpg)

> **Extract the visual identity from any Word template. Regenerate pixel-perfect branded documents from Markdown. Every time. In seconds.**

[![PyPI](https://img.shields.io/pypi/v/edgemint)](https://pypi.org/project/edgemint/)
[![Python](https://img.shields.io/pypi/pyversions/edgemint)](https://pypi.org/project/edgemint/)
[![CI](https://github.com/raphaelmansuy/edgemint/actions/workflows/ci.yml/badge.svg)](https://github.com/raphaelmansuy/edgemint/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://ghcr.io/raphaelmansuy/edgemint)

---

## Why does this exist?

You have a beautiful `.docx` template. Corporate fonts, precise spacing, branded headings. Your designer spent weeks on it.

Now you need to produce 50 reports with that exact look — from Markdown your team writes in Git repos, wikis, and notebooks.

**What happens today:**

```
  THE PAINFUL WAY
  ───────────────────────────────────────────────────────────────
  1. Open Word
  2. Copy-paste your Markdown content
  3. Manually apply Heading 1... Heading 2... Body Text...
  4. Fix the spacing. Again.
  5. Fix the fonts. Again.
  6. Realize the numbered list is wrong. Fix it. Again.
  7. Repeat for the next 49 documents.

  Total time: hours    Errors: guaranteed    Will to live: declining
```

**What should happen:**

```
  THE edgemint WAY
  ───────────────────────────────────────────────────────────────
  1. Extract styles from your template     (once,  ~1 second)
  2. Write content in Markdown             (the fun part)
  3. Run one command                       (< 5 seconds)
  4. Get a perfectly styled .docx          (every time)

  Total time: seconds    Errors: zero    Will to live: restored
```

`edgemint` is a CLI that extracts the complete visual identity from any `.docx`
template into a portable JSON file, then regenerates new documents from Markdown
or AsciiDoc while preserving every font, color, spacing, and border — losslessly.

---

## How it works

```
  YOUR TEMPLATE          YOUR CONTENT           YOUR OUTPUT
  ─────────────          ────────────           ───────────

  ┌────────────┐          ┌────────────┐         ┌────────────┐
  │ branded    │          │ content.md │         │ branded    │
  │ .docx      │          │ (Markdown) │         │ .docx      │
  └─────┬──────┘          └─────┬──────┘         └────────────┘
        │                       │                      ▲
        │ extract-styles        │                      │
        ▼                       │    apply-styles      │
  ┌────────────┐                └─────────────────────►┘
  │ styles.json│
  │ (identity) │
  └────────────┘

  "what it looks like"   "what it says"     "both, together"
```

Two commands. Any template. Any content. Every time.

---

## Install

```bash
# Recommended: install as a CLI tool (works on macOS, Linux, Windows)
pipx install edgemint[pandoc]

# Lightweight (style extraction + diff only, no Pandoc)
pipx install edgemint

# Inside a virtual environment or CI
pip install edgemint[pandoc]

# Docker (zero local dependencies)
docker pull ghcr.io/raphaelmansuy/edgemint:latest
```

> **macOS note**: `pip install` is blocked by Homebrew's Python. Use `pipx install` or activate a virtual environment first.

---

## 60-second demo

```bash
# 1. See what styles are in your template
edgemint info brand.docx

# 2. Extract the visual identity
edgemint extract-styles brand.docx -o styles.json

# 3. Write your content in Markdown, then generate
edgemint apply-styles report.md styles.json -o report.docx
```

Open `report.docx`. Every font, color, and spacing is **identical** to your template.

---

## Full round-trip with images

```bash
# Extract everything: content + styles + media
edgemint extract source.docx -o project/
# → project/content.md   (Pandoc Extended Markdown)
# → project/styles.json  (complete visual identity)
# → project/media/       (all embedded images)

# Edit project/content.md, then regenerate
edgemint apply-styles project/content.md project/styles.json \
  -o rebuilt.docx --media project/media
```

---

## Commands

```
edgemint extract-styles   template.docx  -o styles.json
edgemint extract          document.docx  -o project/
edgemint apply-styles     content.md styles.json  -o output.docx
edgemint apply-styles     content.adoc styles.json  -o output.docx --input-format asciidoc
edgemint diff             old.json new.json
edgemint validate         styles.json
edgemint info             template.docx
edgemint schema
```

| Command | Needs Pandoc? | What it does |
|---------|:---:|---|
| `extract-styles` | No | `.docx` → `styles.json` |
| `extract` | Yes | `.docx` → `content.md` + `styles.json` + `media/` |
| `apply-styles` | Yes | `content.md` + `styles.json` → `.docx` |
| `diff` | No | compare two `styles.json` files |
| `validate` | No | check `styles.json` schema |
| `info` | No | quick `.docx` style summary |
| `schema` | No | print the JSON Schema |

---

## Use in CI/CD

Generate styled documents on every push — no Word needed:

```yaml
# .github/workflows/generate-docs.yml
jobs:
  generate:
    runs-on: ubuntu-latest
    container: ghcr.io/raphaelmansuy/edgemint:latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          for md in reports/*.md; do
            edgemint apply-styles "$md" brand/styles.json \
              -o "output/$(basename $md .md).docx"
          done
      - uses: actions/upload-artifact@v4
        with:
          name: reports
          path: output/*.docx
```

Push Markdown → get styled `.docx` artifacts. Every commit. Automatically.

---

## AI Agent Integration

edgemint is designed to be a **first-class tool for AI coding agents**. When an
agent (Claude, GPT-4o, Gemini, Cursor, etc.) needs to produce a formatted Word
document, the workflow is:

```
  AGENT WORKFLOW
  ──────────────────────────────────────────────────────────────────
  User: "Write a Q3 report using our brand template."

  1. Agent reads styles.json  (knows every branded paragraph/char style)
  2. Agent writes content.md  (Markdown + custom-style annotations)
  3. Agent calls edgemint      edgemint apply-styles content.md styles.json -o report.docx
  4. Agent returns report.docx (pixel-perfect branded output)

  No Word. No manual styling. No human in the loop.
```

This pattern works for:
- **Report generation** — audit reports, weekly updates, release notes
- **Book authoring** — Packt, O'Reilly, or any publisher template
- **Legal documents** — contract templates, NDAs, briefs
- **Engineering docs** — RFCs, architecture proposals, ADRs
- **Batch pipelines** — generate 100 branded PDFs from one template in CI

### Install the Claude Code Skill

The repo ships two ready-to-use Claude Code skills in [`.claude/skills/`](.claude/skills/):

| Skill | Purpose |
|-------|--------|
| [edgemint](.claude/skills/edgemint/SKILL.md) | General DOCX generation for any template |
| [edgemint-packt](.claude/skills/edgemint-packt/SKILL.md) | Packt publisher house-style specialisation |

Install the general skill globally:

```bash
mkdir -p ~/.claude/skills/edgemint
cp .claude/skills/edgemint/SKILL.md ~/.claude/skills/edgemint/SKILL.md
```

Or use it project-locally (Claude Code picks it up automatically):

```bash
# already there — just open Claude Code in this repo
ls .claude/skills/
```

### Conversational example

Once the skill is installed, an agent session looks like this:

```
User:  Extract styles from our brand.docx, then write a two-page
       executive summary about Q3 sales using the template.

Claude: I'll extract the styles first, then write the content.

  $ edgemint extract-styles brand.docx -o styles.json
  ✓ 47 styles extracted

  [writes content.md with correct custom-style annotations]

  $ edgemint apply-styles content.md styles.json -o executive-summary.docx
  ✓ executive-summary.docx (42 KB)

  Done — executive-summary.docx is ready to submit.
```

---

## Audit style changes between template versions

```bash
edgemint diff brand-v1.json brand-v2.json

CHANGED  Heading1
  font.size_pt: 16.0 → 18.0
  font.color: #2F5496 → #1A3C6E
ADDED    Subtitle
REMOVED  BodyTextIndent
```

Version-control your `styles.json` and review brand changes in PRs.

---

## What is preserved

```
  Paragraph styles    LOSSLESS   custom-style fenced divs
  Character styles    LOSSLESS   custom-style bracketed spans
  Bold / italic       LOSSLESS   standard Markdown syntax
  Footnotes           LOSSLESS   [^id] syntax
  Images              LOSSLESS   ![alt](media/x.png)
  Tables              LOSSLESS   pipe / grid tables
  Math (LaTeX)        LOSSLESS   $...$ and $$...$$
  Theme / colors      LOSSLESS   styles.json sidecar
  Headers / footers   LOSSLESS   styles.json sidecar
  ──────────────────────────────────────────────────────
  Track changes       LOST       accepted only
  Comments            LOST       no Markdown equivalent
  VBA / Macros        LOST       stripped (security)
```

No surprises. No silent degradation. Losses are always logged as warnings.

---

## Development workflow

```bash
git clone https://github.com/raphaelmansuy/edgemint
cd edgemint
make bootstrap     # create .venv, install all deps
make doctor        # verify toolchain
make fmt           # auto-format
make lint          # ruff static checks
make test          # full suite, 100% coverage required
make build         # wheel + sdist → dist/
```

### Rebuild the Packt examples

```bash
make examples
```

Requires `examples/packt-style.docx` (real Packt template). Produces:

| File | Description |
|------|-------------|
| `examples/packt-style.styles.json` | extracted style identity |
| `examples/packt-style.bundle/` | full extraction bundle |
| `examples/packt-style-example.docx` | compact style surface test |
| `examples/packt-book-chapter.docx` | long-form chapter proof |
| `examples/01-transformer.docx` | math-heavy transformer chapter |
| `examples/packt-style-author-guide.docx` | author tutorial |

---

## Documentation

| Guide | Audience |
|-------|---------|
| [Quick Start](docs/quick-start.md) | Just getting started |
| [CLI Reference](docs/cli-reference.md) | Every command and flag |
| [Style Guide](docs/style-guide.md) | How to annotate Markdown with styles |
| [CI/CD Integration](docs/cicd-integration.md) | Automated pipelines |
| [Packt Author Guide](docs/packt-author-guide.md) | Publisher content workflows |
| [Architecture](docs/architecture.md) | Design decisions and internals |
| [Release Process](docs/release-process.md) | How to cut a release |
| [edgemint Claude Skill](.claude/skills/edgemint/SKILL.md) | AI agent integration (general) |
| [edgemint-packt Claude Skill](.claude/skills/edgemint-packt/SKILL.md) | AI agent integration (Packt) |

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). The short version:

```bash
make bootstrap && make test   # must pass at 100% coverage
```

All PRs must pass lint + full test suite. See [docs/release-process.md](docs/release-process.md)
for the release checklist.

---

## License

[Apache 2.0](LICENSE) © Raphaël Mansuy
