imprenta 0.1.0__tar.gz

imprenta-0.1.0/.github/scripts/roll_changelog.py

@@ -0,0 +1,99 @@
+"""Move CHANGELOG.md's [Unreleased] entries under a new version heading.
+
+Usage: roll_changelog.py CHANGELOG TAG PREVIOUS_TAG DATE NOTES_OUT [TAG_ALREADY_AT_HEAD]
+       roll_changelog.py --notes CHANGELOG TAG NOTES_OUT
+
+Called by release.yml. Writes the release notes to NOTES_OUT and edits the
+changelog in place; touches neither when there is nothing to release:
+
+- [Unreleased] has entries: they become ``## [X.Y.Z] - DATE`` and an empty
+  [Unreleased] is left above them.
+- [Unreleased] is empty but the commit already shipped as another tag (a manual
+  minor/major bump after the automatic patch): a short ``## [X.Y.Z]`` entry
+  points at that release, whose entries become the notes.
+
+Keep a Changelog link references at the bottom are updated when present.
+
+With --notes, CHANGELOG has already been rolled for TAG (a re-run resuming a
+release whose changelog commit reached main): only the notes are written, the
+same ones the roll produced. Exits 1 if CHANGELOG has no section for TAG.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+HEADING = re.compile(r"^## \[(?P<name>[^\]]+)\]", re.MULTILINE)
+LINKS = re.compile(r"^\[[^\]]+\]: ", re.MULTILINE)
+
+
+def section(text: str, name: str) -> tuple[int, int, int] | None:
+    """(heading start, body start, body end) of the ``## [name]`` section."""
+    for m in HEADING.finditer(text):
+        if m.group("name") == name:
+            body = text.index("\n", m.start()) + 1
+            nxt = HEADING.search(text, body)
+            links = LINKS.search(text, body)
+            ends = [x.start() for x in (nxt, links) if x] + [len(text)]
+            return m.start(), body, min(ends)
+    return None
+
+
+def update_links(text: str, version: str, base: str) -> str:
+    """Point [Unreleased] at the new tag and add a link for the new version."""
+    m = re.search(r"^\[Unreleased\]: (?P<repo>\S+)/compare/\S+\.\.\.HEAD$", text, re.M)
+    if not m:
+        return text
+    repo, tag = m.group("repo"), f"v{version}"
+    link = f"{repo}/compare/{base}...{tag}" if base else f"{repo}/releases/tag/{tag}"
+    new = f"[Unreleased]: {repo}/compare/{tag}...HEAD\n[{version}]: {link}"
+    return text[: m.start()] + new + text[m.end() :]
+
+
+SAME_CODE = re.compile(r"^Same code as (?P<tag>v\S+), released as \S+\.")
+
+
+def rolled_notes(path: str, tag: str, notes_out: str) -> None:
+    text = Path(path).read_text()
+    rolled = section(text, tag.removeprefix("v"))
+    if rolled is None:
+        sys.exit(f"{path} has no section for {tag}")
+    notes = text[rolled[1] : rolled[2]].strip()
+    if (m := SAME_CODE.match(notes)) and (shipped := section(text, m["tag"].removeprefix("v"))):
+        notes = f"{notes}\n\n{text[shipped[1] : shipped[2]].strip()}"
+    Path(notes_out).write_text(notes + "\n")
+
+
+def main(path: str, tag: str, previous: str, date: str, notes_out: str, at_head: str = "") -> None:
+    file = Path(path)
+    text = file.read_text()
+    version = tag.removeprefix("v")
+    unreleased = section(text, "Unreleased")
+    if unreleased is None:
+        return
+    _, body_start, body_end = unreleased
+    body = text[body_start:body_end].strip()
+    base = previous
+    if body:
+        notes = body
+        rolled = f"\n## [{version}] - {date}\n\n{body}\n\n"
+    elif at_head and (shipped := section(text, at_head.removeprefix("v"))):
+        shipped_body = text[shipped[1] : shipped[2]].strip()
+        base = at_head
+        notes = f"Same code as {at_head}, released as {tag}.\n\n{shipped_body}".strip()
+        rolled = f"\n## [{version}] - {date}\n\nSame code as {at_head}, released as {tag}.\n\n"
+    else:
+        return
+
+    text = text[:body_start] + rolled + text[body_end:].lstrip("\n")
+    file.write_text(update_links(text, version, base))
+    Path(notes_out).write_text(notes + "\n")
+
+
+if __name__ == "__main__":
+    if sys.argv[1:2] == ["--notes"]:
+        rolled_notes(*sys.argv[2:])
+    else:
+        main(*sys.argv[1:])

imprenta-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  # PR runs supersede each other. Every other run gets its own group, so each
+  # push to main finishes CI and can be released.
+  group: ci-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      # Ruff only, no project install, at the exact version in uv.lock so CI
+      # and local `uv sync` lint with the same release.
+      - name: Resolve locked ruff version
+        run: |
+          version=$(awk '/^name = "ruff"$/{f=1} f && /^version = /{gsub(/"/,"",$3); print $3; exit}' uv.lock)
+          test -n "$version" || { echo "ruff not found in uv.lock" >&2; exit 1; }
+          echo "RUFF_VERSION=$version" >> "$GITHUB_ENV"
+
+      - name: Lint
+        run: uvx "ruff@$RUFF_VERSION" check src tests
+
+      - name: Format check
+        run: uvx "ruff@$RUFF_VERSION" format --check src tests
+
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history + tags for hatch-vcs versioning
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install
+        run: uv sync --extra dev
+
+      - name: Test
+        run: uv run pytest

imprenta-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,80 @@
+name: Publish
+
+# Publishes to PyPI when a GitHub Release is published, or when release.yml
+# starts it on a new tag. It only runs on a vX.Y.Z tag.
+#
+# Uses PyPI Trusted Publishing (OIDC) — no API token/secret required. Before the
+# first release, configure a Trusted Publisher on PyPI for this project:
+#   PyPI → project "imprenta" → Settings → Publishing → add a GitHub publisher with
+#   owner=jmcmeen, repo=imprenta, workflow=publish.yml, environment=pypi.
+# Also create a GitHub environment named "pypi" (Settings → Environments).
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history + tags for hatch-vcs versioning
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Require a release tag on main
+        run: |
+          # Run by hand on a branch, this would build and upload a dev version;
+          # on a tag off main, code that never went through main and its CI.
+          if [ "$GITHUB_REF_TYPE" != tag ] || ! [[ "$GITHUB_REF_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::Publish only runs on a vX.Y.Z tag, not $GITHUB_REF_TYPE '$GITHUB_REF_NAME'."
+            exit 1
+          fi
+          git fetch -q origin +refs/heads/main:refs/remotes/origin/main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::$GITHUB_REF_NAME isn't on main; only release tags from main are published."
+            exit 1
+          fi
+
+      - name: Build sdist + wheel
+        run: |
+          # Version from the tag this run is on, not `git describe`: when two
+          # tags share a commit, describe can pick the older one.
+          export SETUPTOOLS_SCM_PRETEND_VERSION="${GITHUB_REF_NAME#v}"
+          uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/imprenta
+    permissions:
+      id-token: write # required for trusted publishing
+    steps:
+      - name: Download built distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true # a retried release re-dispatches this

imprenta-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,256 @@
+name: Release
+
+# Cuts a release when a merge to main passes CI: the latest vX.Y.Z tag gets its
+# patch number bumped (v0.1.0 if there are no tags yet). Merges that land while
+# a release is running can share the next release (see below), so a release is
+# per merge in the usual case, not guaranteed for each one.
+# Python packages take their version from that tag via hatch-vcs; a repo whose
+# version lives in files (e.g. Cargo.toml) provides .github/scripts/
+# set_version.sh, which is run with the new version (X.Y.Z). CHANGELOG.md's
+# [Unreleased] entries move under the new version in a github-actions[bot]
+# commit on main, along with any set_version.sh edits; that commit is what gets
+# tagged, and the entries become the release notes. If main has moved on by
+# then, nothing is pushed and this merge isn't released on its own: the release
+# for the newer merge includes it (a manual minor/major run says to run again).
+#
+# For a minor or major release, run this workflow by hand on main ("Run
+# workflow", or `gh workflow run release.yml -f bump=minor`). It releases the
+# head of main with that part bumped; the next merge continues from it. If the
+# merge was already released as a patch, the commit carries both tags. It
+# refuses to run until CI has passed on that commit. If a release is already
+# running and a merge's release queues behind your run, GitHub cancels your
+# pending run in its favor -- Actions shows it as cancelled; run it again.
+#
+# Releasing runs are serialized, and GitHub keeps only the newest pending one,
+# so merges that land close together can share a release. The lock is on the
+# job, so skipped runs (failed CI, dispatch off main) never take that slot.
+# A commit that is already inside the latest release is skipped, so an old run
+# finishing late never gets a newer version than the code after it. Re-running
+# a run whose release exists only re-dispatches publish.yml (which skips files
+# already on PyPI).
+
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Version part to bump
+        type: choice
+        options: [minor, major, patch]
+        default: minor
+
+permissions:
+  contents: write # changelog commit, tag + release
+  actions: write # dispatch publish.yml
+
+jobs:
+  release:
+    name: Tag and release
+    if: >-
+      (github.event_name == 'workflow_run'
+        && github.event.workflow_run.conclusion == 'success'
+        && github.event.workflow_run.event == 'push')
+      || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
+    runs-on: ubuntu-latest
+    concurrency:
+      group: release
+      cancel-in-progress: false
+    env:
+      SHA: ${{ github.event.workflow_run.head_sha || github.sha }}
+      BUMP: ${{ inputs.bump || 'patch' }}
+      GH_TOKEN: ${{ github.token }}
+      BOT_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+          fetch-depth: 0 # all tags
+
+      - name: Require passing CI
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          # A release commit never runs CI (bot pushes don't trigger it), so
+          # check the commit it was made on.
+          tested=$SHA
+          if git rev-parse -q --verify HEAD^ > /dev/null &&
+            [ "$(git log -1 --format=%ae HEAD)" = "$BOT_EMAIL" ] &&
+            git log -1 --format=%s HEAD | grep -q '^Update changelog for '; then
+            tested=$(git rev-parse HEAD^)
+          fi
+          passed=$(gh run list --workflow ci.yml --commit "$tested" --event push \
+            --status success --json databaseId --jq length)
+          if [ "$passed" -eq 0 ]; then
+            echo "::error::CI hasn't passed on $tested yet; wait for it, then run this again."
+            exit 1
+          fi
+
+      - name: Compute version
+        id: version
+        run: |
+          semver='^v[0-9]+\.[0-9]+\.[0-9]+$'
+          bump() {
+            IFS=. read -r major minor patch <<< "${1#v}"
+            case "$BUMP" in
+              major) echo "v$((major + 1)).0.0" ;;
+              minor) echo "v$major.$((minor + 1)).0" ;;
+              *) echo "v$major.$minor.$((patch + 1))" ;;
+            esac
+          }
+          first() { if [ "$BUMP" = major ]; then echo v1.0.0; else echo v0.1.0; fi; }
+          # This commit's releases, oldest first: tags on it, or on a release
+          # commit the bot made on top of it.
+          ours=$(git tag --points-at HEAD | grep -E "$semver" || true)
+          for t in $(git tag --contains HEAD | grep -E "$semver" || true); do
+            if [ "$(git rev-parse "$t^{commit}^")" = "$(git rev-parse HEAD)" ] &&
+              [ "$(git log -1 --format=%ae "$t")" = "$BOT_EMAIL" ] &&
+              git log -1 --format=%s "$t" | grep -q '^Update changelog for '; then
+              ours="$ours $t"
+            fi
+          done
+          ours=$(printf '%s\n' $ours | grep . | sort -uV || true)
+          newest=$(printf '%s\n' $ours | tail -1)
+          if [ "$BUMP" = patch ]; then
+            # A patch run on a released commit retries its newest release.
+            retry=$newest
+          else
+            # A minor or major run retries only its own bump: a tag of this
+            # commit that is exactly that bump of the release before it, or the
+            # first release when there is none before it. (Asking for the same
+            # bump again on the same commit counts as a retry: releasing
+            # identical code under two new minor versions is never wanted.)
+            retry=
+            merged=$(git tag --merged HEAD | grep -E "$semver" || true)
+            for t in $ours; do
+              base=$(printf '%s\n' $merged "$t" | sort -uV | grep -B1 -xF "$t" | grep -vxF "$t" || true)
+              if { [ -n "$base" ] && [ "$(bump "$base")" = "$t" ]; } ||
+                { [ -z "$base" ] && [ "$t" = "$(first)" ]; }; then
+                retry=$t
+              fi
+            done
+          fi
+          if [ -n "$retry" ]; then
+            echo "$SHA is already $retry; retrying its release and publish."
+            echo "tag=$retry" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          latest=$(git tag --list 'v*' | grep -E "$semver" | sort -V | tail -1 || true)
+          if [ -z "$latest" ]; then
+            next=$(first)
+          elif git merge-base --is-ancestor HEAD "$latest" &&
+            ! printf '%s\n' $ours | grep -qxF "$latest"; then
+            echo "$SHA is already included in $latest; nothing to do."
+            exit 0
+          else
+            next=$(bump "$latest")
+          fi
+          echo "Releasing $next ($BUMP bump; previous: ${latest:-none})"
+          {
+            echo "tag=$next"
+            echo "new=true"
+            echo "previous=$latest"
+            echo "at_head=$newest"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Roll changelog and set version
+        id: changelog
+        if: steps.version.outputs.new == 'true'
+        env:
+          TAG: ${{ steps.version.outputs.tag }}
+          PREVIOUS: ${{ steps.version.outputs.previous }}
+          AT_HEAD: ${{ steps.version.outputs.at_head }}
+        run: |
+          notes="$RUNNER_TEMP/notes.md"
+          # True if a newer commit on main includes $SHA. Fails the step if main
+          # no longer contains $SHA at all (rewritten): releasing it would
+          # publish code that isn't on main, and skipping would hide that.
+          main_moved_past_sha() {
+            # Called inside `if`, where set -e is off: check the fetch by hand
+            # so a stale origin/main never decides a release.
+            if ! git fetch -q origin +refs/heads/main:refs/remotes/origin/main; then
+              echo "::error::Fetching main failed; can't tell whether it moved past $SHA."
+              exit 1
+            fi
+            [ "$(git rev-parse origin/main)" != "$SHA" ] || return 1
+            if ! git merge-base --is-ancestor "$SHA" origin/main; then
+              echo "::error::main no longer contains $SHA; not releasing $TAG."
+              exit 1
+            fi
+          }
+          # Releasing $SHA as is would leave its entries under [Unreleased]
+          # (they'd appear in the next release too) and miss the version files.
+          skip_release() {
+            echo "::notice::main moved past $SHA; not releasing $TAG here. The release for the newer merge includes this one (for a manual minor/major run, run it again)."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          }
+          # A re-run after this changelog commit reached main but the release
+          # wasn't created: release that commit, with the notes it rolled,
+          # rather than rolling $SHA again (that push would be rejected).
+          git fetch -q origin +refs/heads/main:refs/remotes/origin/main
+          rolled=$(git log --format='%H%x09%P%x09%ae%x09%s' "$SHA..origin/main" |
+            awk -F '\t' -v sha="$SHA" -v bot="$BOT_EMAIL" -v subject="Update changelog for $TAG" \
+              '$2 == sha && $3 == bot && $4 == subject { print $1 }')
+          if [ -n "$rolled" ]; then
+            echo "Release commit for $TAG is already on main ($rolled); releasing that."
+            echo "sha=$rolled" >> "$GITHUB_OUTPUT"
+            if git show "$rolled:CHANGELOG.md" > "$RUNNER_TEMP/CHANGELOG.md" 2> /dev/null &&
+              python3 .github/scripts/roll_changelog.py --notes "$RUNNER_TEMP/CHANGELOG.md" "$TAG" "$notes"; then
+              echo "notes=$notes" >> "$GITHUB_OUTPUT"
+            fi
+            exit 0
+          fi
+          if [ -f CHANGELOG.md ]; then
+            python3 .github/scripts/roll_changelog.py CHANGELOG.md "$TAG" "$PREVIOUS" \
+              "$(date -u +%Y-%m-%d)" "$notes" "$AT_HEAD"
+          fi
+          if [ -f .github/scripts/set_version.sh ]; then
+            bash .github/scripts/set_version.sh "${TAG#v}"
+          fi
+          # Stage everything, so files the hook creates or stages are included.
+          git add -A
+          if git diff --cached --quiet; then
+            echo "Nothing under [Unreleased] and no version files; using generated notes."
+            # Nothing to push, so main moving on isn't caught by the push below.
+            if main_moved_past_sha; then
+              skip_release
+            fi
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "$BOT_EMAIL"
+          git commit -qm "Update changelog for $TAG"
+          # Fast-forward only: if main moved past $SHA, leave it alone.
+          if git push origin HEAD:refs/heads/main; then
+            echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+            if [ -s "$notes" ]; then
+              echo "notes=$notes" >> "$GITHUB_OUTPUT"
+            else
+              echo "Nothing under [Unreleased]; using generated notes."
+            fi
+            exit 0
+          fi
+          if ! main_moved_past_sha; then
+            echo "::error::Pushing the release commit for $TAG failed, and main hasn't moved."
+            exit 1
+          fi
+          skip_release
+
+      - name: Create release
+        if: steps.version.outputs.tag != '' && steps.changelog.outputs.skip != 'true'
+        env:
+          TAG: ${{ steps.version.outputs.tag }}
+          TARGET: ${{ steps.changelog.outputs.sha || env.SHA }}
+          NOTES: ${{ steps.changelog.outputs.notes }}
+        run: |
+          if ! gh release view "$TAG" > /dev/null 2>&1; then
+            if [ -n "$NOTES" ]; then notes=(--notes-file "$NOTES"); else notes=(--generate-notes); fi
+            gh release create "$TAG" --target "$TARGET" --title "$TAG" "${notes[@]}"
+          fi
+          # A release made with GITHUB_TOKEN doesn't fire publish.yml's release
+          # trigger, so start it directly on the new tag. Repos with nothing to
+          # publish have no publish.yml.
+          if [ -f .github/workflows/publish.yml ]; then
+            gh workflow run publish.yml --ref "$TAG"
+          fi

imprenta-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.DS_Store

imprenta-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-23
+
+### Added
+
+- **The content arranger.** `content/<name>.md` files are arranged into products by
+  `catalog.<name>.yaml` files: `defaults`, `rendering` (render variants), `strings`
+  (labels), `terms` (glossary column aliases), `groups`, `recipes` (shapes with
+  `$name` substitution) and `products` (an ordered `parts` list, a `theme`, and the
+  fields `status`, `version`, `variants`, `tags`). Nothing in the engine knows what the
+  content is about or what language it is in.
+- **Generated parts.** `toc` (positional: lists every heading placed after it, with
+  page numbers resolved by Paged.js; settings `depth`, `pages`, `title`) and `terms`
+  (a glossary built from the content's term tables, with a label column when the
+  terms come from more than one labelled file).
+- **Styled parts.** Any content part may carry `{style: <name>, toc: false}`; the
+  build wraps every part in `<div class="part part-<name> style-<style>">` for the
+  theme to style. A cover is a content file with `style: cover`. A content file
+  that is only comments (a placeholder) is skipped, so it never costs a page.
+- **Rendering.** pandoc + pagedjs-cli (Paged.js in headless Chrome) for PDF variants,
+  pandoc EPUB 3 for `renderer: epub` variants, with size and palette css layers.
+  Incremental builds keyed on file mtimes plus a stamp of the catalog rows and the
+  imprenta version.
+- **Targets.** `(catalog, product, variant)`; `imprenta build` takes `<catalog>`,
+  `<product>`, `<catalog>/<product>`, each optionally `.<variant>`, or nothing for
+  everything; `--tag` narrows to products carrying a tag. `imprenta affected --since`
+  maps changed paths to targets for incremental CI.
+- **Validation.** `imprenta check` enforces the content rules (one leading H1, H2
+  sections, max H4, front matter) and the catalog rules (every name resolves, settings
+  per part kind, recipes, themes, publishing fields, rendering layers).
+- **Catalog editing.** `imprenta.edit` writes catalogs through ruamel.yaml's
+  round-trip mode so comments survive.
+- **The manager.** `imprenta manager` (extra `imprenta[tui]`): a Textual dashboard of
+  every product with a product screen for sync-free publishing fields, variant
+  subscriptions, builds and outputs.
+- **API.** `imprenta.Project` as the entry point: catalogs, targets, build, check.
+

imprenta-0.1.0/CITATION.cff

@@ -0,0 +1,12 @@
+# Citation metadata (Citation File Format 1.2.0 — https://citation-file-format.github.io).
+# `version`/`date-released` are omitted so this file never drifts from the actual release.
+cff-version: 1.2.0
+title: "imprenta: a content arranger and styler"
+message: "If you use this software, please cite it using this metadata."
+type: software
+authors:
+  - family-names: McMeen
+    given-names: John
+    email: johnmcmeen@gmail.com
+repository-code: "https://github.com/jmcmeen/imprenta"
+license: MIT

imprenta-0.1.0/CLAUDE.md

@@ -0,0 +1,62 @@
+# imprenta: conventions for Claude Code
+
+## What this is
+
+A content arranger and styler. It is a Python package (`src/imprenta`) with a CLI (`imprenta`), an
+optional Textual TUI (`imprenta[tui]`) and a public API (`imprenta.Project`).
+The README describes the model; this file is about working on the code.
+
+## Hard rules
+
+- **Nothing content-specific.** No countries, languages, brands, slang, guides
+  or books in code, comments, docstrings, tests or docs. Examples use neutral
+  names (`intro`, `alpha`, `almanac`, `leaflet`, `release`). What a tag means,
+  where outputs are published, what a glossary column is called: all of that is
+  the content repo's business and lives in its catalog or its own scripts.
+- **The engine never injects or shifts headings.** What is in a content file
+  is what renders. Themes style; they do not restructure.
+- **A catalog has exactly these sections:** `defaults`, `rendering`,
+  `strings`, `terms`, `groups`, `recipes`, `products`. Adding a field is an
+  API change: update `catalog.py`, `check.py`, the README and the CHANGELOG
+  together.
+- **Everything in a parts list is a name.** No sigils, no catch-all. Names
+  resolve as generated part, group, content file, in that order.
+- **Catalogs are written only through `imprenta.edit`** (ruamel round-trip).
+  PyYAML's dump drops comments. ruamel attaches a comment to the key before
+  it, so popping a key can take the next comment with it.
+- **Paged.js matches break rules by selector**, not computed style. To keep an
+  element from breaking, exclude it from the rule; a later `break-before:
+  auto` does not undo an earlier `page`.
+
+## Layout
+
+```text
+src/imprenta/
+  project.py   Project: root, dirs, catalogs (cached on mtime), content names, targets, build, check
+  catalog.py   Catalog: sections, rendering, product_def (recipes + $name), plan, resolve_parts, render_row
+  content.py   front matter, comments, headings, word counts, css-safe names
+  parts.py     generated parts (toc marker, terms glossary), part wrapping, assemble
+  render.py    pandoc / pagedjs-cli / Chrome, doctor, asset copying, the packaged toc.lua
+  build.py     freshness (inputs + stamp), building one target
+  targets.py   Target, all_targets, affected_targets, changed_since, spec parsing
+  check.py     the validator (content rules + catalog rules)
+  edit.py      round-trip catalog editing
+  cli.py       argparse entry point; tui.py  the manager (textual, optional)
+  data/toc.lua the pandoc filter behind the positional table of contents
+tests/         pytest; conftest builds a two-catalog sample project in tmp_path
+```
+
+## Working here
+
+- `make install` (uv sync with the dev and TUI extras), `make test`, `make
+  lint`, `make fmt`, `make check` (what CI runs). Python ≥ 3.10.
+- Versions come from `vX.Y.Z` tags via hatch-vcs. `release.yml` bumps the patch
+  on every green merge to main and rolls `CHANGELOG.md`'s Unreleased section
+  into the release; a minor or major bump is a manual run of that workflow.
+  Add every user-visible change under `## [Unreleased]` in the same commit.
+- `publish.yml` publishes to PyPI on a release (trusted publishing, environment
+  `pypi`). Content repos pin `imprenta==X.Y.Z`.
+- Tests never call pandoc or Chrome. Rendering is exercised from a content repo
+  (`imprenta build`), the logic around it is what the suite covers.
+- The TUI builds through `python -m imprenta build …` in a worker thread so
+  its output streams into the log pane; it never imports make.

imprenta-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John McMeen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.