@typeroll/mcp-server 0.45.79 → 0.45.81

package/workspace-templates/scripts/typeroll/prepare_image.py

@@ -0,0 +1,64 @@
+"""Convert a reviewed local original to an sRGB JPEG; never upload or change CMS content.
+Requires Pillow with ImageCms. Preserve the untouched original in the source archive.
+CMYK needs its actual embedded or supplied ICC profile. Never guess a CMYK profile.
+Unprofiled RGB/gray requires --assume-srgb after review. Output must not exist.
+"""
+import argparse
+import hashlib
+import io
+import json
+from pathlib import Path
+
+
+def prepare(source, output, source_profile=None, assume_srgb=False, quality=95):
+    from PIL import Image, ImageCms, ImageOps
+    source, output = Path(source), Path(output)
+    if output.exists() or source.resolve() == output.resolve():
+        raise ValueError('Output already exists; choose a new derivative path.')
+    if output.suffix.lower() not in ('.jpg', '.jpeg'):
+        raise ValueError('Choose a .jpg or .jpeg output.')
+    if not 1 <= quality <= 100:
+        raise ValueError('JPEG quality must be from 1 to 100.')
+    with Image.open(source) as original:
+        if getattr(original, 'n_frames', 1) != 1:
+            raise ValueError('Multi-page/animated originals require an explicit frame decision.')
+        if 'A' in original.getbands() or 'transparency' in original.info:
+            raise ValueError('Transparent originals need a reviewed background or a PNG workflow.')
+        profile_bytes = Path(source_profile).read_bytes() if source_profile else original.info.get('icc_profile')
+        image = ImageOps.exif_transpose(original)
+        target = ImageCms.ImageCmsProfile(ImageCms.createProfile('sRGB'))
+        if profile_bytes:
+            profile = ImageCms.ImageCmsProfile(io.BytesIO(profile_bytes))
+            converted = ImageCms.profileToProfile(image, profile, target, outputMode='RGB')
+        elif image.mode in ('RGB', 'L') and assume_srgb:
+            converted = image.convert('RGB')
+        else:
+            raise ValueError('Missing source ICC profile. CMYK cannot be safely guessed; supply the correct --source-profile. For reviewed unprofiled RGB/gray only, use --assume-srgb.')
+        # No source EXIF/GPS/caption metadata is copied into the public derivative.
+        with output.open('xb') as destination:
+            converted.save(destination, format='JPEG', quality=quality, subsampling=0, icc_profile=target.tobytes())
+    with Image.open(output) as check:
+        check.load()
+        if check.mode != 'RGB' or not check.info.get('icc_profile'):
+            raise ValueError('Output verification failed; do not upload the derivative.')
+        dimensions = list(check.size)
+    return {'source_sha256': hashlib.sha256(source.read_bytes()).hexdigest(),
+            'output_sha256': hashlib.sha256(output.read_bytes()).hexdigest(),
+            'width': dimensions[0], 'height': dimensions[1], 'colour_space': 'sRGB',
+            'source_profile': 'supplied' if source_profile else 'embedded' if profile_bytes else 'assumed sRGB',
+            'uploaded': False}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('source', type=Path)
+    parser.add_argument('output', type=Path)
+    parser.add_argument('--source-profile', type=Path)
+    parser.add_argument('--assume-srgb', action='store_true')
+    parser.add_argument('--quality', type=int, default=95)
+    args = parser.parse_args()
+    print(json.dumps(prepare(args.source, args.output, args.source_profile, args.assume_srgb, args.quality), indent=2))
+
+
+if __name__ == '__main__':
+    main()

package/workspace-templates/workflows/design.md

@@ -28,3 +28,38 @@ Record deliberate departures in decisions.md with scope and owner approval.
 Use a QA round per review: method, pages/viewports, expected differences, results,
 unverified items and remaining defects. Record platform findings in
 qa/typeroll-platform-feedback.md; do not bury them in workaround CSS.
+
+## Site tokens before block overrides
+
+Core 0.2.106 / template capabilities 0.54.0 adds palette names in all colour
+fields and named typography/spacing steps. Check the connected capability
+version; on older renderers use `var(--color-surface)` rather than a bare name.
+
+Set colours and font families in site settings, then use named styles and
+palette names in blocks. Do not write hex, rgb or font-family literals in block
+content. Prefer `primary`, `secondary`, `accent`, `background`, `surface`, `text`,
+`text_light`, and `on_primary`/`on_secondary`/`on_accent` for text on brand colours.
+Use `surface_hover` for a darker interactive surface (derived automatically
+unless explicitly configured). Existing semantic roles should be reused; a
+new visual shade is not automatically a new semantic role. For a derived shade
+use `color-mix(in srgb, var(--color-surface) 92%, var(--color-primary))`.
+For an additional role not in the native palette, define a named site style
+or a site CSS variable derived from existing palette variables, and document it.
+
+Choose `heading`, `body` or `mono` for fonts. Font families belong only in the
+site's `fonts` settings. Use type-size steps `xs`, `sm`, `md`, `lg`, `xl`, `2xl`,
+`3xl`; spacing `none`, `xs`, `sm`, `md`, `lg`, `xl`; line height `tight`, `snug`,
+`normal`, `relaxed`, `loose`. Presentation fields accept responsive maps of these
+names, for example `font_size_px: {mobile: "md", desktop: "lg"}`. Read the field
+schema: counts, widths and breakpoints are not spacing steps. Pixel values are
+explicit exceptions, not the default authoring method. Configure scales in
+`design_scales`, then reuse them in role styles and blocks.
+
+Record deliberate exceptions in `decisions.md`, with source/block, reason and
+review criteria (for example white text on a photograph). Run `lint_design_tokens`
+before launch and after major design changes. It warns, never blocks launch.
+Use the starter's `scripts/typeroll/color_tokens.py` for an exact-match dry run;
+review the plan before applying it in a dedicated Version. Equal hex values can
+mean different roles: never automatically choose between background and text.
+Verify a primary/surface change in a test Version across header, footer, cards,
+menus and buttons, then restore the test settings. Do not republish automatically.

package/workspace-templates/workflows/migration.md

@@ -82,3 +82,48 @@ Page/partial block writes update working copies; check `saved` and use
 `commit_working_copy` with `target: {kind: "page"|"partial", id: "..."}`.
 Page templates save immediately and do not have working copies. REST read envelopes and
 MCP tool text are different layers; `call.py` returns the decoded tool result.
+
+## Design token check
+
+Follow workflows/design.md for palette/font roles and named scales. Run
+`lint_design_tokens` before launch and after major design changes. Review exact
+colour replacements with scripts/typeroll/color_tokens.py; record deliberate
+exceptions in decisions.md. Preserve text independently from design changes.
+
+## Source retirement, analytics and domain preparation
+
+Before old hosting is retired, follow workflows/source-media.md: preserve unused
+and print originals in a private archive with independently verified checksums.
+Only approved web assets enter the CMS. Use ICC-aware conversion for CMYK/TIFF.
+
+Enable Analytics through the authorized Typeroll API/MCP (`update_app` or the
+Organization analytics tools), then read back settings and verify the beacon and
+cookies on the actual artifact. Resolve missing provider scopes through the
+normal approval flow. A separately authorized provider-side setup with a supplied
+beacon token is an alternative, not a way to bypass Organization permissions.
+Never expose a provider API token as a public beacon token.
+
+From Core 0.2.106, saving future hosts does not redirect normal publication.
+Keep using `trigger_deploy` to update and review the current/temporary address.
+Read `next_publication` in `read_publishing_domains` for the destination.
+Shortly before DNS changes, deliberately call `prepare_publishing_domain_change`
+with the current revision. It prepares the last successful public snapshot,
+not later unpublished CMS edits. Review its frozen indexing settings and DNS
+requirements, then approve traffic separately. If another normal publication
+succeeds while the candidate waits, prepare again: an outdated snapshot cannot
+replace newer published content. There is no need to clear saved future hosts.
+To correct candidate indexing, save the intended setting, publish normally, and
+prepare again. Temporary-host protection keeps the review address noindex even
+when the published authored setting permits indexing on the future host.
+Keep MX/SPF and unrelated DNS unchanged; review any validation window and obtain
+the already-defined traffic-switch authorization.
+
+## Owner-supplied facts and photos
+
+Record owner statements, source and confirmation date. Preserve approved copy
+under `text: preserve`; do not silently delete dates/prices or rewrite it into
+"timeless" language. Under `text: renew`, propose removing stale details or using
+recurring-event wording only when a source supports recurrence. Flag uncertain
+facts for review or keep new Pages in draft; missing evidence does not prove that
+an event stopped. Link to the actual organiser when relevant. Upload approved
+photos with SHA-256 verification and review focal points at mobile/desktop widths.

package/workspace-templates/workflows/new-site.md

@@ -15,3 +15,10 @@ Do not publish, change DNS or send messages without explicit approval.
 
 The CMS owns current content and settings. The repository owns the brief, rules,
 decisions and evidence. Load recipes when needed, not the whole manual.
+
+## Design token check
+
+Follow workflows/design.md for palette/font roles and named scales. Run
+`lint_design_tokens` before launch and after major design changes. Review exact
+colour replacements with scripts/typeroll/color_tokens.py; record deliberate
+exceptions in decisions.md. Preserve text independently from design changes.

package/workspace-templates/workflows/source-media.md

@@ -0,0 +1,50 @@
+# Preserve source media before retirement
+
+This is a separate owner-approved archive, not an import of every old file into
+the CMS. Do not delete source files or cancel old hosting as part of this routine.
+
+1. Inventory originals and downloads from the source API/export, including files
+   absent from published pages. Include drafts, private records and historical
+   attachments when authorized. A public sitemap or REST response cannot prove
+   the library is complete. Keep the export under ignored `sources/private/`.
+2. Compare with the new site's references, including templates, partials and
+   retained URLs. Record used, unused and uncertain files. "Unused" is not an
+   instruction to delete. Preserve print originals even when a web derivative exists.
+3. Agree a private archive destination, its owning account, retention and access.
+   Verify account/bucket identity and that public bucket/custom-domain access is
+   disabled. Use the owner's credentials through their secret manager; never put
+   credentials in scripts or manifests. Do not provision or expose a bucket silently.
+4. Copy with bounded concurrency and bounded reads, stream large files and use
+   resumable transfers when supported. Preserve a collision-safe key derived from
+   the full source host/path, not just the filename. Never overwrite a different
+   object merely because the basename matches.
+5. Record source URL, destination key, source ID, byte count, SHA-256, media type,
+   title/alt/caption, copy time and verification state in a private manifest.
+   ETag is not universally MD5 (multipart objects and providers differ). Use a
+   documented checksum API or stream the destination back and compare SHA-256
+   and size. Metadata claiming a hash is not proof of the uploaded bytes.
+6. Resume only verified matches; report every unavailable source and hash conflict.
+   Verify a restore from the archive, including a large file. Keep an independent
+   private copy of the manifest. The owner reviews completeness and grants a
+   separate old-host retirement decision. This archive does not preserve old
+   public URLs by itself: keep URL parity/redirect acceptance separate.
+
+## Prepare print images for the web
+
+Use `scripts/typeroll/prepare_image.py` for a reviewed local TIFF or other original.
+Install Pillow with ImageCms in an isolated environment. It applies EXIF
+orientation, converts through the embedded (or explicitly supplied) ICC profile
+to sRGB, embeds the sRGB profile, strips source EXIF metadata and writes a new
+JPEG. It never changes the original, uploads files or edits a Page.
+
+```sh
+python3 scripts/typeroll/prepare_image.py sources/private/original.tif sources/private/web.jpg
+```
+
+CMYK without the correct profile fails; obtain the actual source profile instead
+of guessing. `--source-profile sources/private/original.icc` supplies it.
+Unprofiled RGB/gray requires an explicit `--assume-srgb` decision. Multi-page,
+animated and transparent images require a separate reviewed workflow. Compare
+colour, subject framing and sharpness visually before upload. Upload through the
+normal integrity-checked media flow and choose alt/caption text independently.
+Store the tool's hash report privately; never commit customer images or archives.