@typeroll/mcp-server 0.45.77 → 0.45.79

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

@@ -0,0 +1,72 @@
+"""Check published page assets, including relative URLs and srcset. CSS backgrounds need visual QA."""
+import argparse
+import concurrent.futures
+from html.parser import HTMLParser
+import json
+import urllib.parse
+import trlib
+from check_url_parity import origin, fetch, probe
+
+
+class Assets(HTMLParser):
+    def __init__(self, base):
+        super().__init__(convert_charrefs=True)
+        self.base, self.urls = base, set()
+
+    def handle_starttag(self, tag, attrs):
+        data = dict(attrs)
+        values = []
+        if tag in ('img', 'source', 'video', 'audio', 'script'):
+            values.extend(data[k] for k in ('src', 'poster') if data.get(k))
+        if tag == 'link' and data.get('rel') == 'stylesheet':
+            values.append(data.get('href', ''))
+        href = data.get('href', '')
+        if tag == 'a' and ('download' in data or urllib.parse.urlsplit(href).path.lower().endswith(('.pdf', '.jpg', '.jpeg', '.png', '.webp', '.avif', '.svg', '.zip'))):
+            values.append(href)
+        if data.get('srcset') and not data['srcset'].strip().startswith('data:'):
+            values.extend(item.strip().split()[0] for item in data['srcset'].split(',') if item.strip())
+        for value in values:
+            url = urllib.parse.urljoin(self.base, value)
+            if urllib.parse.urlsplit(url).scheme in ('http', 'https'):
+                self.urls.add(url)
+
+
+def check(url):
+    status, location, _ = fetch(url, 'HEAD')
+    # HEAD is not supported everywhere; redirects must resolve too.
+    if status in (405, 501) or location:
+        status = probe(url).get('status', 0)
+    return {'url': url, 'status': status, 'ok': status == 200}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('origin', type=origin)
+    args = parser.parse_args()
+    pages = [p for p in trlib.all_pages() if p.get('status') in ('published', 'unlisted')]
+    errors, assets = [], set()
+    for page in pages:
+        if not page.get('url'):
+            errors.append({'page_id': page['id'], 'error': 'missing_resolved_route'})
+            continue
+        route = urllib.parse.urlsplit(page['url'])
+        url = args.origin + (route.path or '/') + ('?' + route.query if route.query else '')
+        evidence = probe(url, expected_page=True)
+        if not evidence.get('ok'):
+            errors.append({'page_id': page['id'], **evidence})
+            continue
+        status, _, body = fetch(evidence['final_url'])
+        if status != 200:
+            errors.append({'page_id': page['id'], 'status': status})
+            continue
+        parser = Assets(evidence['final_url'])
+        parser.feed(body.decode('utf8', 'replace'))
+        assets.update(parser.urls)
+    with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
+        results = list(pool.map(check, sorted(assets)))
+    print(json.dumps({'pages': len(pages), 'page_errors': errors, 'assets': results}, indent=2))
+    return 1 if not pages or errors or any(not item['ok'] for item in results) else 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

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

@@ -0,0 +1,13 @@
+"""Pre-deploy gate: list every Page and partial with an unsaved working copy (Page templates save immediately).
+Deploys build saved content only, and previews with include_working_copy hide the difference.
+usage: python3 scripts/typeroll/check_unsaved.py   (exit 1 when something is unsaved)"""
+import os, sys
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import trlib
+SITE = trlib.site_id()
+bad = [t for t in trlib.containers() if t["kind"] != "template"
+       and trlib.call("read_working_copy", {"site_id": SITE, "target": t}).get("working_copy")]
+for t in bad:
+    print("unsaved:", t["kind"], t["id"])
+print("unsaved total:", len(bad))
+sys.exit(1 if bad else 0)

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

@@ -0,0 +1,74 @@
+"""Read-only URL continuity check on an explicitly supplied deployed origin."""
+import argparse
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+import trlib
+
+UA = 'Typeroll-Starter-QA/1.0 (+https://typeroll.com/docs/)'
+
+
+def fetch(url, method='GET'):
+    request = urllib.request.Request(url, method=method, headers={'User-Agent': UA})
+    for attempt in range(2):
+        try:
+            with urllib.request.build_opener(trlib.NoRedirect).open(request, timeout=30) as response:
+                return response.status, response.headers.get('Location'), response.read() if method == 'GET' else b''
+        except urllib.error.HTTPError as error:
+            if error.code in (502, 503, 504) and attempt == 0:
+                continue
+            return error.code, error.headers.get('Location'), b''
+        except (OSError, TimeoutError):
+            if attempt:
+                return 0, None, b''
+
+
+def origin(value):
+    parsed = urllib.parse.urlsplit(value)
+    if parsed.scheme not in ('http', 'https') or not parsed.netloc or parsed.username or parsed.password or parsed.query or parsed.fragment or parsed.path not in ('', '/'):
+        raise ValueError('Supply a plain deployed HTTP(S) origin')
+    return value.rstrip('/')
+
+
+def probe(url, expected_page=False):
+    initial, seen, hops = url, set(), []
+    for _ in range(6):
+        if url in seen:
+            return {'error': 'redirect_loop', 'hops': hops}
+        seen.add(url)
+        status, location, _ = fetch(url)
+        if status not in (301, 302, 303, 307, 308) or not location:
+            slash = bool(hops) and urllib.parse.urlsplit(initial)._replace(path=urllib.parse.urlsplit(initial).path.rstrip('/')) == urllib.parse.urlsplit(hops[0])._replace(path=urllib.parse.urlsplit(hops[0]).path.rstrip('/'))
+            maximum = 1 if expected_page else 2 if slash else 1
+            acceptable_page_hop = not expected_page or not hops or (len(hops) == 1 and slash)
+            ok = status == 200 and len(hops) <= maximum and acceptable_page_hop
+            return {'ok': ok, 'status': status, 'hops': hops, 'final_url': url}
+        url = urllib.parse.urljoin(url, location)
+        if urllib.parse.urlsplit(url).scheme not in ('http', 'https'):
+            return {'error': 'unsupported_redirect_scheme', 'hops': hops}
+        hops.append(url)
+    return {'error': 'too_many_redirects', 'hops': hops}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('origin', type=origin)
+    parser.add_argument('--show-excluded', action='store_true')
+    args = parser.parse_args()
+    report = []
+    for row in trlib.all_migration_urls():
+        if row.get('status') == 'excluded' and not args.show_excluded:
+            continue
+        for path in sorted(set([row['path']] + (row.get('observed_paths') or []))):
+            # Inventory spellings must be paths, not a silent change of tested host.
+            if not path.startswith('/') or path.startswith('//'):
+                raise ValueError('Inventory contains a non-local path')
+            url = args.origin + urllib.parse.quote(path, safe='/%?=&:+')
+            report.append({'path': path, **probe(url, row.get('status') == 'migrated')})
+    print(json.dumps(report, indent=2))
+    return 1 if not report or any(not row.get('ok') for row in report) else 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

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

@@ -0,0 +1,59 @@
+"""Compare saved source HTML (or one WP REST record) to a captured target.
+Template titles are included exactly once by explicit source title/target selector.
+This reports differences, never rewrites content or approves a migration.
+"""
+import argparse
+import difflib
+from html.parser import HTMLParser
+import json
+from pathlib import Path
+import re
+
+
+class Text(HTMLParser):
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.words, self.skip = [], 0
+    def handle_starttag(self, tag, attrs):
+        if tag in ('script', 'style'):
+            self.skip += 1
+        elif tag in ('p', 'div', 'li', 'br', 'h1', 'h2', 'h3', 'h4'):
+            self.words.append(' ')
+    def handle_endtag(self, tag):
+        if tag in ('script', 'style'):
+            self.skip = max(0, self.skip - 1)
+        elif tag in ('p', 'div', 'li', 'h1', 'h2', 'h3', 'h4'):
+            self.words.append(' ')
+    def handle_data(self, value):
+        if not self.skip:
+            self.words.append(value)
+    # HTMLParser excludes comments. Do not strip tags with a regexp.
+
+
+def tokens(value):
+    parser = Text()
+    parser.feed(value)
+    return re.findall(r'\w+|[^\w\s]', ''.join(parser.words))
+
+
+def main():
+    args = argparse.ArgumentParser(description=__doc__)
+    args.add_argument('source', help='HTML fragment or one saved WP REST record (.json)')
+    args.add_argument('target', help='JSON from capture_text.cjs')
+    args.add_argument('--source-title', default='', help='For an HTML source whose title is template-owned')
+    opts = args.parse_args()
+    source = Path(opts.source).read_text()
+    if opts.source.endswith('.json'):
+        record = json.loads(source)
+        source = record['title']['rendered'] + ' ' + record['content']['rendered']
+    else:
+        source = opts.source_title + ' ' + source
+    target = json.loads(Path(opts.target).read_text())
+    before, after = tokens(source), re.findall(r'\w+|[^\w\s]', target['text'])
+    changes = [line for line in difflib.ndiff(before, after) if line.startswith(('+ ', '- '))]
+    print(json.dumps({'source_tokens': len(before), 'target_tokens': len(after), 'changes': changes}, ensure_ascii=False, indent=2))
+    return int(bool(changes))
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

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

@@ -0,0 +1,20 @@
+"""Tile screenshots into contact sheets for fast visual review of many pages.
+usage: python3 contact_sheet.py <out-prefix> <cols> <tile-width> <png> [<png> ...]
+Each tile shows the top of a screenshot (height = 3.2 x width) labelled with its file name."""
+import sys, os
+from PIL import Image, ImageDraw
+out, cols, tw, files = sys.argv[1], int(sys.argv[2]), int(sys.argv[3]), sys.argv[4:]
+th = int(tw * 3.2)
+per = cols * 2
+for n, start in enumerate(range(0, len(files), per)):
+    chunk = files[start:start + per]
+    sheet = Image.new("RGB", (cols * tw, 2 * (th + 20)), "white")
+    d = ImageDraw.Draw(sheet)
+    for i, f in enumerate(chunk):
+        im = Image.open(f).convert("RGB")
+        im = im.resize((tw, int(im.height * tw / im.width))).crop((0, 0, tw, th))
+        x, y = (i % cols) * tw, (i // cols) * (th + 20)
+        sheet.paste(im, (x, y + 20))
+        d.text((x + 3, y + 3), os.path.basename(f)[:40], fill="red")
+    sheet.save(f"{out}-{n}.png")
+    print(f"{out}-{n}.png")

package/workspace-templates/scripts/typeroll/layout_trace.cjs

@@ -0,0 +1,33 @@
+// Explain vertical spacing: computed margin/padding/gap of every ancestor of a selector and of the next
+// section down to its first heading. Works on a signed preview link (reads the inner frame) or a public URL.
+// usage: node layout_trace.js <url> [width=390] [selector=h1]
+const qa = require('./browser.cjs');
+const { chromium } = qa;
+(async () => {
+  const [,, url, width = '390', sel = 'h1'] = process.argv;
+  const b = await chromium.launch();
+  const p = await b.newPage({viewport: {width: +width, height: 900}});
+  await qa.open(p, url);
+  const f = p.mainFrame();
+  try { console.log(await f.evaluate((sel) => {
+    const out = [];
+    const show = (lab, el) => {
+      if (!el) return;
+      const c = getComputedStyle(el), r = el.getBoundingClientRect();
+      out.push(`${lab} <${el.tagName.toLowerCase()} ${el.getAttribute('data-block') || String(el.className).slice(0, 40)}> top=${Math.round(r.top)} h=${Math.round(r.height)} margin=${c.marginTop}/${c.marginBottom} padding=${c.paddingTop}/${c.paddingBottom} gap=${c.rowGap} radius=${c.borderRadius}`);
+    };
+    const target = document.querySelector(sel);
+    if (!target) throw Error('Selector not found');
+    const sec = target.closest('[data-block="section"]') || target;
+    const chain = []; for (let a = target; a && a !== document.body; a = a.parentElement) chain.push(a);
+    chain.reverse().forEach((x, i) => show('ancestor' + i, x));
+    for (let s = sec.nextElementSibling; s; s = s.nextElementSibling) {
+      show('next', s);
+      const h = s.querySelector('h1,h2,h3');
+      if (h) { const ch = []; for (let q = h; q && q !== s; q = q.parentElement) ch.push(q); ch.reverse().forEach((x, i) => show('inside' + i, x)); break; }
+    }
+    show('header', document.querySelector('header'));
+    return out.join('\n');
+  }, sel));
+  } finally { await b.close(); }
+})().catch(qa.fail);

package/workspace-templates/scripts/typeroll/shoot_hosted.cjs

@@ -0,0 +1,26 @@
+const qa = require('./browser.cjs');
+const [origin, out, paths, ...args] = process.argv.slice(2);
+(async () => {
+  const browser = await qa.chromium.launch();
+  const report = [];
+  try {
+    for (const route of paths.split(',')) {
+      const url = new URL(route, origin);
+      if (url.origin !== new URL(origin).origin) throw Error('Paths must stay on the selected origin');
+      for (const width of qa.widths(args)) {
+        const page = await browser.newPage({ viewport: { width, height: 900 } });
+        const failed = [];
+        page.on('requestfailed', r => failed.push({ host: new URL(r.url()).hostname, kind: 'network' }));
+        page.on('response', r => { if (r.status() >= 400) failed.push({ host: new URL(r.url()).hostname, status: r.status() }); });
+        await qa.open(page, url.href); await qa.settle(page);
+        const result = { path: route, width, ...await qa.inspect(page), failed };
+        const name = require('node:crypto').createHash('sha256').update(route).digest('hex').slice(0, 12);
+        await qa.screenshot(page, `${out}/${name}-${width}.png`);
+        report.push(result);
+        await page.close();
+      }
+    }
+    console.log(JSON.stringify(report, null, 2));
+    if (report.some(r => r.overflow || r.incompleteImages.length || r.h1 !== 1 || r.failed.length || !r.scrollCoverageComplete)) process.exitCode = 1;
+  } finally { await browser.close(); }
+})().catch(qa.fail);

package/workspace-templates/scripts/typeroll/shootframe.cjs

@@ -0,0 +1,16 @@
+const qa = require('./browser.cjs');
+const [out, url, ...args] = process.argv.slice(2);
+(async () => {
+  const browser = await qa.chromium.launch();
+  try {
+    for (const width of qa.widths(args)) {
+      const page = await browser.newPage({ viewport: { width, height: 900 } });
+      const hosts = new Set();
+      page.on('request', r => { try { hosts.add(new URL(r.url()).hostname); } catch {} });
+      await qa.open(page, url); await qa.settle(page);
+      await qa.screenshot(page, `${out}-${width}.png`);
+      console.log(JSON.stringify({ width, ...await qa.inspect(page), hosts: [...hosts] }));
+      await page.close();
+    }
+  } finally { await browser.close(); }
+})().catch(qa.fail);

package/workspace-templates/scripts/typeroll/sweep_blocks.example.py

@@ -0,0 +1,23 @@
+"""Pattern: change one kind of block on every Page, Page template and partial, then save.
+Example: set last_row "start" on every core/grid that centers its last row. Dry run lists; --apply writes.
+Copy and edit MATCH/PATCH for other sweeps. Templates save immediately; Pages and partials must be committed. Refuses existing unsaved work."""
+import os, sys
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import trlib
+SITE = trlib.site_id()
+MATCH = lambda b: b.get("type") == "core/grid" and (b.get("data") or {}).get("last_row") == "center"
+PATCH = {"last_row": "start"}
+apply = "--apply" in sys.argv
+for tgt in trlib.containers():
+    tree = trlib.call("get_page_blocks", {"site_id": SITE, "target": tgt})
+    hits = [b for b in trlib.walk(tree.get("blocks", tree) if isinstance(tree, dict) else tree) if MATCH(b)]
+    if not hits:
+        continue
+    print(tgt["kind"], tgt["id"], len(hits))
+    if apply:
+        if tgt['kind'] != 'template' and trlib.call('read_working_copy', {'target': tgt}).get('working_copy'):
+            raise RuntimeError('Unsaved work exists; review it before this sweep')
+        for b in hits:
+            trlib.call("update_block", {"site_id": SITE, "target": tgt, "block_id": b["id"], "data": PATCH})
+        if tgt["kind"] in ("page", "partial"):
+            trlib.call("commit_working_copy", {"site_id": SITE, "target": tgt})

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

@@ -0,0 +1,212 @@
+"""Small, version-bound MCP helper. Credentials are injected, never persisted.
+No automatic retries for mutations. Run from the workspace root.
+"""
+import hashlib
+import json
+import os
+from pathlib import Path
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):
+        return None  # Never forward Authorization or signed PUTs to another URL.
+
+
+def workspace():
+    for directory in (Path.cwd(), *Path.cwd().parents):
+        file = directory / 'typeroll.json'
+        if file.is_file():
+            value = json.loads(file.read_text())
+            if not all(value.get(k) for k in ('portal', 'organization_id', 'site_id', 'version')):
+                raise ValueError('Complete portal, organization_id, site_id and version in typeroll.json first')
+            origin = urllib.parse.urlsplit(value['portal'])
+            if origin.username or origin.password or origin.query or origin.fragment or origin.path not in ('', '/'):
+                raise ValueError('portal must be a plain origin')
+            if origin.scheme != 'https' and not (origin.scheme == 'http' and origin.hostname in ('localhost', '127.0.0.1', '::1')):
+                raise ValueError('portal requires HTTPS (HTTP is allowed only on loopback)')
+            return value
+    raise ValueError('Run from a workspace containing typeroll.json')
+
+
+class Client:
+    def __init__(self, config=None):
+        self.config = config or workspace()
+        self.url = self.config['portal'].rstrip('/') + '/api/mcp?tools=full'
+        self.session = None
+        self.sequence = 0
+        self.tools = None
+        self.verified = False
+        self.opener = urllib.request.build_opener(NoRedirect)
+
+    def rpc(self, method, params=None, notify=False):
+        self.sequence += 1
+        body = {'jsonrpc': '2.0', 'method': method}
+        if params is not None:
+            body['params'] = params
+        if not notify:
+            body['id'] = self.sequence
+        key = os.environ.get('TYPEROLL_API_KEY')
+        if not key:
+            raise ValueError('Inject TYPEROLL_API_KEY privately before running')
+        headers = {'Authorization': 'Bearer ' + key, 'Content-Type': 'application/json',
+                   'Accept': 'application/json, text/event-stream'}
+        if self.session:
+            headers['Mcp-Session-Id'] = self.session
+        request = urllib.request.Request(self.url, data=json.dumps(body).encode(), headers=headers)
+        try:
+            with self.opener.open(request, timeout=180) as response:
+                self.session = response.headers.get('Mcp-Session-Id') or self.session
+                raw = response.read().decode()
+        except urllib.error.HTTPError as error:
+            raise RuntimeError(f'MCP HTTP {error.code}; no mutation was retried') from None
+        if notify:
+            return None
+        result = decode_rpc(raw, self.sequence)
+        if 'error' in result:
+            raise RuntimeError(f"MCP RPC error {result['error'].get('code')}")
+        return result['result']
+
+    def initialize(self):
+        self.rpc('initialize', {'protocolVersion': '2025-03-26', 'capabilities': {},
+                              'clientInfo': {'name': 'typeroll-workspace', 'version': '1'}})
+        self.rpc('notifications/initialized', notify=True)
+        self.tools = {}
+        cursor = None
+        seen = set()
+        while True:
+            result = self.rpc('tools/list', {'cursor': cursor} if cursor else {})
+            self.tools.update({t['name']: t for t in result['tools']})
+            cursor = result.get('nextCursor')
+            if not cursor:
+                break
+            if cursor in seen:
+                raise RuntimeError('tools/list repeated its cursor')
+            seen.add(cursor)
+
+    def call(self, tool, args=None):
+        if self.tools is None:
+            self.initialize()
+        if tool not in self.tools:
+            raise ValueError(f'Tool unavailable: {tool}')
+        if not self.verified:
+            info = self.invoke('get_site', {})
+            if info.get('organization_id') != self.config['organization_id'] or info.get('id') != self.config['site_id']:
+                raise ValueError('Connected Organization/Site does not match typeroll.json; nothing was written')
+            self.verified = True
+        return self.invoke(tool, args or {})
+
+    def invoke(self, tool, args):
+        props = self.tools[tool]['inputSchema'].get('properties', {})
+        data = dict(args)
+        for key, wanted in [('site_id', self.config['site_id']), ('version', self.config['version'])]:
+            if key in data and data[key] != wanted:
+                raise ValueError(f'{key} differs from typeroll.json; change the binding explicitly')
+            if key in props:
+                data[key] = wanted
+        if 'version' not in props and self.config['version'] != 'main' and tool != 'get_site':
+            raise ValueError(f'{tool} has no version parameter; refusing an implicit main-version operation')
+        result = self.rpc('tools/call', {'name': tool, 'arguments': data})
+        if result.get('isError'):
+            raise RuntimeError(f'{tool} failed; inspect through your authenticated MCP client (no retry)')
+        if 'structuredContent' in result:
+            return result['structuredContent']
+        text = ''.join(c.get('text', '') for c in result.get('content', []) if c.get('type') == 'text')
+        return json.loads(text)
+
+
+def decode_rpc(raw, request_id):
+    if raw.lstrip().startswith('{'):
+        value = json.loads(raw)
+        if value.get('id') != request_id:
+            raise ValueError('MCP response did not contain the matching request ID')
+        return value
+    # Streamable HTTP may include notifications, multiline data, and keepalives.
+    for event in raw.replace('\r\n', '\n').split('\n\n'):
+        data = '\n'.join(line[5:].lstrip() for line in event.splitlines() if line.startswith('data:'))
+        if data:
+            value = json.loads(data)
+            if value.get('id') == request_id:
+                return value
+    raise ValueError('MCP response did not contain the matching request ID')
+
+
+_client = None
+
+
+def call(tool, args=None):
+    global _client
+    if _client is None:
+        _client = Client()
+    return _client.call(tool, args)
+
+
+def site_id():
+    return workspace()['site_id']
+
+
+def walk(blocks):
+    for block in blocks or []:
+        yield block
+        yield from walk(block.get('children'))
+        for slot in block.get('slots') or []:
+            yield from walk(slot)
+
+
+def all_pages():
+    cursor, seen = None, set()
+    while True:
+        args = {'limit': 200, **({'cursor': cursor} if cursor else {})}
+        result = call('list_pages', args)
+        yield from result['pages']
+        cursor = result.get('next_cursor')
+        if not cursor:
+            return
+        if cursor in seen:
+            raise RuntimeError('list_pages repeated its cursor')
+        seen.add(cursor)
+
+
+def all_migration_urls():
+    offset = 0
+    while True:
+        result = call('list_migration_urls', {'limit': 1000, 'offset': offset})
+        rows = result['urls']
+        yield from rows
+        offset += len(rows)
+        if not rows or offset >= result.get('total_matching', float('inf')):
+            return
+
+
+def containers():
+    for page in all_pages():
+        yield {'kind': 'page', 'id': page['id']}
+    for kind, tool, key in [('template', 'list_page_templates', 'templates'), ('partial', 'list_partials', 'partials')]:
+        result = call(tool)
+        rows = result if isinstance(result, list) else result.get(key, result.get('page_templates'))
+        if not isinstance(rows, list):
+            raise ValueError(f'Unexpected response from {tool}')
+        for row in rows:
+            yield {'kind': kind, 'id': row['id']}
+
+
+def upload(file, content_type, alt=''):
+    content = Path(file).read_bytes()
+    sha = hashlib.sha256(content).hexdigest()
+    mint = call('create_upload_url', {'filename': Path(file).name, 'content_type': content_type,
+                                    'size': len(content), 'alt_text': alt})
+    if urllib.parse.urlsplit(mint['upload_url']).scheme != 'https':
+        raise ValueError('Signed upload must use HTTPS')
+    request = urllib.request.Request(mint['upload_url'], data=content, method='PUT', headers={'Content-Type': content_type})
+    try:
+        with urllib.request.build_opener(NoRedirect).open(request, timeout=120) as response:
+            response.read()
+    except Exception:
+        raise RuntimeError('Signed upload failed; URL withheld; no automatic retry') from None
+    result = call('finalize_media', {'media_id': mint['media_id'], 'expected_sha256': sha})
+    evidence = result.get('result', result)
+    if evidence.get('sha256') != sha:
+        raise ValueError('Finalize did not confirm the source SHA-256; do not reference this asset')
+    return {'media_id': mint['media_id'], 'cdn_url': mint['cdn_url'], 'sha256': sha}

package/workspace-templates/workflows/design.md

@@ -0,0 +1,30 @@
+# Layout defaults and owner decisions
+
+Use current native composition starters and block schemas. These defaults are
+starting points, not permission to overwrite an approved design.
+
+- Keep incomplete grid rows left-aligned (`last_row: start`). Never enlarge one
+  peer card just to fill the gap. Center only on an explicit owner request.
+- Prefer `core/navigation_menu` with `core/navigation_links` desktop/mobile slots
+  for a header drawer (below 1024 px). Read tr-header-footer; test 1023/1024 px.
+- Separate dense footer about text from the link grid. Give it a readable width
+  and a larger gap; inspect 390/1024/1280/1536 px. Equal columns need equal density.
+- Sections own gutters. Do not erase side padding with `padding: 3rem 0` when
+  only vertical spacing is intended. Wrap column-slot contents in a flow
+  container with article rhythm when they need vertical block spacing.
+- Give cards one clear destination. Use whole_card_link without action_label
+  or download actions. Check excerpt, image, whitespace and keyboard activation.
+- Do not fade body text with opacity. Verify actual text/background contrast,
+  current links on light/dark navigation, and all states.
+- Preserve image subjects across widths. Choose contain/original sizing when
+  cropping or upscaling is not intended. Hero crop, text placement, plates,
+  corner treatment and category-page composition are project decisions in
+  brief/brand.md, not a universal design.
+- After migration, check heading hierarchy, unchanged preserved text, HTML
+  comments, links with ../, and the home SEO title/suffix. Shared headings and
+  titles must not be duplicated in body content.
+
+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.

package/workspace-templates/workflows/migration.md

@@ -33,3 +33,52 @@ Track import, block reconstruction, separate text/design review, candidate
 publication and domain cutover as separate milestones. Import completion is not
 launch approval. All four text/design combinations use the same block hierarchy
 and URL continuity contract. Planning choices are not migration API fields.
+
+## Repeatable reconstruction and acceptance
+
+Read workflows/design.md and scripts/README.md. First check whether public
+WordPress REST + HTML covers the source; use tr-migrate-wp's access decision
+table before asking for a helper plugin. Inventory both Pages and posts plus
+internal links and known old slugs. A sitemap alone is not complete.
+
+Discard HTML comments before extracting text, resolve relative links against
+the source, and keep an explicit old URL map. Do not redirect deleted content
+to the home page merely to get a 200. Preserve/renew text and design separately.
+Use capture_text.cjs + compare_text.py for preserved text with explicit selectors.
+
+Before every authorized test deployment run check_unsaved.py (Pages and partials).
+Deploy saved content to the agreed protected test host, then run check_url_parity.py,
+check_assets.py and shoot_hosted.cjs. Check whole-card targets with
+card-stacking-check.cjs and inspect actual desktop/mobile screenshots. Record a
+QA round and platform findings. Review on the owner's phone when possible.
+Domain preparation/cutover and production indexing follow their own explicit
+approval scope and the platform's current guided flow; do not bypass readiness.
+Do not request a second approval for a step the owner has already authorized.
+
+
+## Native controls and publication checks
+
+On Core 0.2.103 / MCP 0.45.79 or later, discover the actual block schemas first.
+Use column `content_gap_px`, responsive section `padding_y`, heading-role
+`space_before`/`space_after`, hero focal/fit/text-position fields and image
+`never_upscale` instead of one-off CSS. Responsive block keys start at `mobile`,
+not `base`. For vertical-only spacing, do not reset horizontal padding with CSS
+shorthand. Optional `click_to_load` videos need an explicit poster if desired;
+choose a first-party poster to avoid early provider requests.
+
+`import_sitemap` can include public WordPress REST (`include_wordpress: true`)
+and a bounded crawl (`crawl_pages: 10`). Record truncation and access warnings.
+A `matched_draft` URL is accounted for in the CMS but not ready for launch.
+Resolve `unpublished_targets`, redirect loops/chains and actual deployed parity.
+
+A deploy with working copies returns `unsaved_content`; review the targets.
+Save explicitly or obtain approval to publish saved content only using
+`allow_unsaved: true`. Never silently save somebody else's work.
+
+Keep the bound Organization/Site/Version explicit. A site API key cannot switch
+to another Organization: use an authorized OAuth connection or a separate key.
+Read the schema for target envelopes and pagination; do not guess aliases.
+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.