@maccesar/titools 5.1.1 → 5.2.1

package/skills/ti-game-assets/references/vector-sources.md

@@ -0,0 +1,21 @@
+# Editable vector and procedural sources
+
+Use an existing SVG/procedural workflow when the project uses it or the user requests editable art generated with code. Integrated `image_gen` remains the default for raster drawing creation/edits; it is not a requirement to replace authored vectors. Rasterizing an SVG is an export step, not image-model generation.
+
+## Source of truth
+
+Keep the editable SVG, generator and parameters as canonical sources; retain individual full-canvas PNG renders as reproducible derivatives. Avoid making a generated PNG the only editable master. Preserve original/legacy source when it has a documented purpose. Name symbols and groups by meaningful parts (hull, cockpit, lights, propulsion, appendages), with explicit `viewBox`, proportions and pivots. Parameterize palette, poses and damage overlays without shifting silhouette or anchor accidentally.
+
+Record deterministic seeds for procedural distributions. Use a maintained SVG rasterizer already in the project, such as `rsvg-convert`/librsvg, and record its version, font dependencies, antialiasing and target dimensions. Rasterizer changes can change bytes: regenerate and review the affected set rather than merely updating hashes. Avoid hidden system-font or external-image dependencies in gameplay graphics.
+
+Reuse a build that emits PNG sheets, runtime catalogs/frame maps, source/generator/output hashes, contact sheets and animation/parallax previews together. The runtime consumes generated PNG/catalog data, not the offline generator. Verify missing/empty cells, frame bounds, dimensions, anchor consistency, stale output hashes and repeat seams. Run it twice in a disposable output directory to check determinism in a fixed environment. Do not infer human authorship from a PNG compression filter or overwrite policy: preserve authored assets through explicit provenance.
+
+Render at the declared logical proportions and preview at actual game sizes, in grayscale and relevant color-vision simulations. Distinguish roles by silhouette/symbol as well as color. Preserve warning readability under reduced-flash settings; do not silently change mechanics, flashes or accessibility preferences while exporting.
+
+## Manifest extension
+
+Keep `source` pointing at the PNG render inspected by the bundled validator; add `vector_source` pointing at its existing SVG master. The validator checks an SVG root and finite positive `viewBox` extents, not vector aesthetics or generation dependencies. Record generator, parameters and render settings in provenance. Optional top-level `build.files` maps source/generator/output paths to SHA-256 hashes; validation detects modified declared files. Include *all* relevant dependencies, not just outputs. Hash agreement does not prove a build was run or that a rasterizer is correct.
+
+## Evidence from Guardian
+
+`docs/art/source/guardian-parts.svg` holds named symbols/editable groups. `docs/scripts/generate-art.js` creates PNGs, runtime catalog and review sheets. `docs/scripts/verify-art.js` checks hashes, cells, animation frames and background edges. `docs/art/README.md` documents the renderer and why its high-resolution antialiased art uses smoothing. These are reusable design choices, not a requirement to copy its cell sizes, frame counts or art.

package/skills/ti-game-assets/scripts/alpha_tools.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Inspect alpha; explicitly remove reviewed exterior residue into new files."""
+import argparse
+import json
+import math
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+
+THRESHOLDS = (1, 4, 8, 16, 32)
+
+
+def bbox(alpha, threshold):
+    return alpha.point(lambda value: 255 if value >= threshold else 0).getbbox()
+
+
+def analyze(image):
+    alpha = image.getchannel('A')
+    histogram = alpha.histogram()
+    return {
+        'dimensions': list(image.size),
+        'alpha_range': list(alpha.getextrema()),
+        'translucent_pixels': sum(histogram[1:255]),
+        'visible_pixels': sum(histogram[1:]),
+        'bounding_boxes': {str(t): bbox(alpha, t) for t in THRESHOLDS},
+    }
+
+
+def rectangle(values, size):
+    x0, y0, x1, y1 = values
+    if not (0 <= x0 < x1 <= size[0] and 0 <= y0 < y1 <= size[1]):
+        raise ValueError('rectangle must be nonempty and inside the source canvas')
+    return tuple(values)
+
+
+def clean(image, protected):
+    alpha = image.getchannel('A')
+    retained = Image.new('L', image.size, 0)
+    retained.paste(alpha.crop(protected), protected[:2])
+    result = image.copy()
+    result.putalpha(retained)
+    return result
+
+
+def preview(before, after=None):
+    images = [before] if after is None else [before, after]
+    cell = 280
+    output = Image.new('RGB', (cell * len(images), (cell + 24) * 3), 'white')
+    draw = ImageDraw.Draw(output)
+    for column, source in enumerate(images):
+        scaled = source.copy()
+        scaled.thumbnail((cell, cell), Image.Resampling.NEAREST)
+        for row, background in enumerate(('checker', '#eeeeee', '#181818')):
+            x, y = column * cell, row * (cell + 24) + 24
+            panel = Image.new('RGBA', (cell, cell), background if row else '#cccccc')
+            if row == 0:
+                painter = ImageDraw.Draw(panel)
+                for cy in range(0, cell, 16):
+                    for cx in range(0, cell, 16):
+                        if (cx // 16 + cy // 16) % 2:
+                            painter.rectangle((cx, cy, cx + 15, cy + 15), fill='#999999')
+            panel.alpha_composite(scaled)
+            output.paste(panel.convert('RGB'), (x, y))
+            draw.text((x + 4, y - 20), ('original' if column == 0 else 'candidate') + ' / ' + background, fill='black')
+            for threshold, color in zip(THRESHOLDS, ('red', 'orange', 'lime', 'cyan', 'magenta')):
+                box = bbox(source.getchannel('A'), threshold)
+                if box:
+                    sx, sy = scaled.width / source.width, scaled.height / source.height
+                    draw.rectangle((x + box[0] * sx, y + box[1] * sy,
+                                    x + (box[2] - 1) * sx, y + (box[3] - 1) * sy), outline=color)
+    return output
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('source', type=Path)
+    parser.add_argument('--profile', choices=('pixel-art', 'hard-surface', 'soft-fx'), default='hard-surface')
+    parser.add_argument('--logical-size', nargs=2, type=int, metavar=('W', 'H'))
+    parser.add_argument('--threshold', type=int, default=8)
+    parser.add_argument('--protect', nargs=4, type=int, metavar=('X0', 'Y0', 'X1', 'Y1'))
+    parser.add_argument('--auto-protect', action='store_true')
+    parser.add_argument('--reason', help='reviewed residue and justification for the protected region')
+    parser.add_argument('--clean', type=Path, help='new PNG output; omit for analysis only')
+    crop = parser.add_mutually_exclusive_group()
+    crop.add_argument('--crop', action='store_true')
+    crop.add_argument('--crop-box', nargs=4, type=int, metavar=('X0', 'Y0', 'X1', 'Y1'))
+    parser.add_argument('--report', type=Path)
+    parser.add_argument('--preview', type=Path)
+    args = parser.parse_args()
+    try:
+        if not 1 <= args.threshold <= 255:
+            raise ValueError('threshold must be 1..255')
+        if args.logical_size and min(args.logical_size) <= 0:
+            raise ValueError('logical size must be positive')
+        if args.protect and args.auto_protect:
+            raise ValueError('choose explicit or automatic protection, not both')
+        if not args.clean and (args.crop or args.crop_box or args.protect or args.auto_protect):
+            raise ValueError('protection and crop flags require --clean')
+        outputs = [p.resolve() for p in (args.clean, args.report, args.preview) if p]
+        if len(outputs) != len(set(outputs)) or args.source.resolve() in outputs:
+            raise ValueError('outputs must be distinct from each other and the source')
+        if any(p.exists() for p in outputs):
+            raise ValueError('refusing to overwrite an existing output')
+        with Image.open(args.source) as opened:
+            source = opened.convert('RGBA')
+        report = {'source': str(args.source), 'profile': args.profile, 'analysis': analyze(source)}
+        candidate = None
+        if args.clean:
+            if not args.reason or not args.reason.strip():
+                raise ValueError('cleaning requires --reason documenting the review')
+            if args.profile == 'soft-fx' and (not args.protect or args.auto_protect):
+                raise ValueError('soft-fx requires an explicit protected region')
+            if args.profile == 'pixel-art' and not args.logical_size:
+                raise ValueError('pixel-art cleaning requires --logical-size')
+            padding = [math.ceil(source.size[i] / args.logical_size[i]) for i in (0, 1)] if args.logical_size else [1, 1]
+            if args.protect:
+                protected = rectangle(args.protect, source.size)
+            elif args.auto_protect:
+                detected = bbox(source.getchannel('A'), args.threshold)
+                if not detected:
+                    raise ValueError('no content at threshold; preserve source and inspect lower thresholds')
+                protected = (max(0, detected[0] - padding[0]), max(0, detected[1] - padding[1]),
+                             min(source.width, detected[2] + padding[0]), min(source.height, detected[3] + padding[1]))
+            else:
+                raise ValueError('cleaning requires --protect or reviewed --auto-protect')
+            candidate = clean(source, protected)
+            report['cleanup'] = {
+                'protected_region': protected, 'threshold': args.threshold,
+                'logical_size': args.logical_size, 'logical_pixel_padding': padding,
+                'reason': args.reason, 'region_mode': 'explicit' if args.protect else 'automatic-trial',
+                'removed_pixels': report['analysis']['visible_pixels'] - analyze(candidate)['visible_pixels'],
+                'analysis': analyze(candidate),
+            }
+            trim = args.crop_box or (bbox(candidate.getchannel('A'), 1) if args.crop else None)
+            if (args.crop or args.crop_box) and not bbox(candidate.getchannel('A'), 1):
+                raise ValueError('cannot crop empty content')
+            if trim:
+                trim = rectangle(trim, source.size)
+                visible = bbox(candidate.getchannel('A'), 1)
+                if visible and not (trim[0] <= visible[0] and trim[1] <= visible[1] and trim[2] >= visible[2] and trim[3] >= visible[3]):
+                    raise ValueError('crop box would discard visible content')
+            report['export'] = {'path': str(args.clean), 'offset': list(trim[:2]) if trim else [0, 0],
+                                'source_dimensions': list(source.size),
+                                'dimensions': [trim[2] - trim[0], trim[3] - trim[1]] if trim else list(source.size)}
+        # Build comparison before writing any output. It uses common source canvases.
+        comparison = preview(source, candidate) if args.preview else None
+        if args.clean:
+            (candidate.crop(trim) if trim else candidate).save(args.clean, format='PNG')
+        if args.preview:
+            comparison.save(args.preview, format='PNG')
+        encoded = json.dumps(report, indent=2)
+        if args.report:
+            args.report.write_text(encoded + '\n', encoding='utf-8')
+        print(encoded)
+    except (ValueError, OSError) as error:
+        parser.error(str(error))
+
+
+if __name__ == '__main__':
+    main()

package/skills/ti-game-assets/scripts/requirements.txt

@@ -0,0 +1 @@
+Pillow>=10

package/skills/ti-game-assets/scripts/validate_manifest.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""Validate per-set game art and sound contracts, files, frames and parallax."""
+import argparse
+from collections import Counter, defaultdict
+import json
+import hashlib
+import re
+import wave
+import xml.etree.ElementTree as ET
+import math
+from pathlib import Path
+
+from PIL import Image
+
+FAMILIES = {'players', 'enemies', 'allies', 'obstacles', 'ammunition', 'rewards', 'ambient', 'backgrounds', 'technical'}
+
+
+def numbers(value, length, positive=False):
+    return (isinstance(value, list) and len(value) == length
+            and all(type(n) in (int, float) and math.isfinite(n) and (not positive or n > 0) for n in value))
+
+
+def dimensions(value):
+    return numbers(value, 2, True) and all(type(n) is int for n in value)
+
+
+def validate(data, root):
+    errors = []
+    counts = []
+
+    def require(condition, message):
+        if not condition:
+            errors.append(message)
+
+    def source_path(value, label):
+        if not isinstance(value, str) or not value:
+            errors.append(label + ': missing source')
+            return None
+        path = (root / value).resolve()
+        if not path.is_file():
+            errors.append(label + ': source not found: ' + value)
+            return None
+        return path
+
+    build = data.get('build')
+    if build is not None:
+        files = build.get('files') if isinstance(build, dict) else None
+        require(isinstance(files, dict) and bool(files), 'build.files must be a nonempty path-to-SHA256 object')
+        for filename, digest in files.items() if isinstance(files, dict) else []:
+            valid_hash = isinstance(digest, str) and re.fullmatch(r'[0-9a-f]{64}', digest) is not None
+            require(valid_hash, 'build: invalid SHA256 for ' + filename)
+            path = source_path(filename, 'build')
+            if path and valid_hash:
+                require(hashlib.sha256(path.read_bytes()).hexdigest() == digest, 'build: stale source/output hash: ' + filename)
+
+    require(data.get('schema_version') == 1, 'schema_version must be 1')
+    contracts = data.get('contracts', {})
+    sets = data.get('sets', [])
+    require(isinstance(contracts, dict) and bool(contracts), 'contracts must be a nonempty object')
+    require(isinstance(sets, list) and bool(sets), 'sets must be a nonempty list')
+    if not isinstance(contracts, dict) or not isinstance(sets, list):
+        return errors, counts
+    seen_sets = set()
+    for group in sets:
+        if not isinstance(group, dict):
+            errors.append('set must be an object')
+            continue
+        name = group.get('id')
+        require(isinstance(name, str) and bool(name) and name not in seen_sets, 'set ids must be unique nonempty strings')
+        if not isinstance(name, str):
+            continue
+        seen_sets.add(name)
+        label = name + ': '
+        contract = contracts.get(group.get('contract'))
+        if not isinstance(contract, dict):
+            errors.append(label + 'unknown contract')
+            continue
+        expected = Counter()
+        definitions = contract.get('resources', [])
+        expected_sounds = Counter()
+        require(isinstance(definitions, list), label + 'contract resources must be a list')
+        for definition in definitions if isinstance(definitions, list) else []:
+            resource, family, variant, state = (definition.get(k) for k in ('resource', 'family', 'variant', 'state'))
+            frames = definition.get('frames')
+            if not all(isinstance(v, str) and v for v in (resource, family, variant, state)) or type(frames) is not int or frames < 1:
+                errors.append(label + 'invalid resource definition')
+                continue
+            require(family in FAMILIES, label + 'unknown resource family ' + family)
+            for frame in range(frames):
+                expected[(resource, family, variant, state, frame)] += 1
+        require(all(n == 1 for n in expected.values()), label + 'duplicate contract resource definition')
+        sound_defs = contract.get('sounds', [])
+        require(isinstance(sound_defs, list), label + 'contract sounds must be a list')
+        for definition in sound_defs if isinstance(sound_defs, list) else []:
+            sound, variants = definition.get('sound'), definition.get('variants')
+            if not isinstance(sound, str) or not sound or not isinstance(variants, list) or not variants or not all(isinstance(v, str) and v for v in variants):
+                errors.append(label + 'invalid sound definition')
+                continue
+            expected_sounds.update((sound, variant) for variant in variants)
+        require(all(n == 1 for n in expected_sounds.values()), label + 'duplicate sound contract variant')
+        require(bool(expected or expected_sounds), label + 'contract must require visual or sound assets')
+        assets, sounds = group.get('assets', []), group.get('sounds', [])
+        require(isinstance(assets, list) and isinstance(sounds, list), label + 'assets and sounds must be lists')
+        if not isinstance(assets, list) or not isinstance(sounds, list):
+            continue
+        actual = Counter()
+        ids = set()
+        asset_by_id = {}
+        alignment = defaultdict(list)
+        sequences = defaultdict(list)
+        for asset in assets:
+            identity = asset.get('id')
+            require(isinstance(identity, str) and bool(identity) and identity not in ids, label + 'asset ids must be unique strings')
+            if not isinstance(identity, str):
+                continue
+            ids.add(identity)
+            asset_by_id[identity] = asset
+            fields = [asset.get(k) for k in ('resource', 'family', 'variant', 'state')]
+            frame = asset.get('frame')
+            if not all(isinstance(v, str) and v for v in fields) or type(frame) is not int or frame < 0:
+                errors.append(label + identity + ': invalid identity/frame')
+                continue
+            actual[tuple(fields) + (frame,)] += 1
+            sequences[tuple(fields)].append(frame)
+            size, canvas, pivot = (asset.get(k) for k in ('dimensions', 'canvas', 'pivot'))
+            require(dimensions(size), label + identity + ': dimensions must be positive integers')
+            require(dimensions(canvas), label + identity + ': canvas must be positive integers')
+            require(numbers(pivot, 2), label + identity + ': pivot must be finite coordinates')
+            require(size == canvas, label + identity + ': master must retain its common canvas')
+            if dimensions(canvas) and numbers(pivot, 2):
+                require(all(0 <= pivot[i] <= canvas[i] for i in (0, 1)), label + identity + ': pivot outside canvas')
+            alignment[tuple(fields[:3])].append((canvas, pivot, asset.get('logical_size')))
+            require(type(asset.get('transparency')) is bool, label + identity + ': transparency must be Boolean')
+            style = asset.get('style')
+            require(style in ('pixel-art', 'hard-surface', 'soft-fx', 'hd'), label + identity + ': unknown style')
+            if style == 'pixel-art':
+                require(dimensions(asset.get('logical_size')), label + identity + ': pixel-art requires logical_size')
+            require(isinstance(asset.get('provenance'), dict) and bool(asset['provenance'].get('prompt')),
+                    label + identity + ': provenance.prompt required')
+            if 'vector_source' in asset:
+                vector = source_path(asset['vector_source'], label + identity + ' vector')
+                if vector:
+                    try:
+                        svg = ET.parse(vector).getroot()
+                        require(svg.tag in ('svg', '{http://www.w3.org/2000/svg}svg'), label + identity + ': vector source must have SVG root')
+                        viewbox = [float(n) for n in svg.get('viewBox', '').replace(',', ' ').split()]
+                        require(numbers(viewbox, 4) and viewbox[2] > 0 and viewbox[3] > 0,
+                                label + identity + ': SVG requires finite viewBox with positive extents')
+                    except (ET.ParseError, ValueError, OSError) as error:
+                        errors.append(label + identity + ': unreadable SVG: ' + str(error))
+            path = source_path(asset.get('source'), label + identity)
+            if path:
+                try:
+                    with Image.open(path) as image:
+                        require(image.format == 'PNG', label + identity + ': master must be PNG')
+                        require(list(image.size) == size, label + identity + ': source dimensions mismatch')
+                        alpha = image.convert('RGBA').getchannel('A')
+                        require(alpha.getextrema()[1] > 0, label + identity + ': empty image')
+                        if asset.get('transparency') is True:
+                            require(('A' in image.getbands() or 'transparency' in image.info) and alpha.getextrema()[0] < 255,
+                                    label + identity + ': real transparency required')
+                        elif asset.get('transparency') is False:
+                            require(alpha.getextrema()[0] == 255, label + identity + ': declared opaque source contains transparency')
+                except OSError as error:
+                    errors.append(label + identity + ': unreadable image: ' + str(error))
+        require(actual == expected, label + 'resource/frame contract incomplete or contains unexpected/duplicate entries')
+        for key, frames in sequences.items():
+            require(frames == list(range(len(frames))), label + str(key) + ': frames must appear in contiguous order from zero')
+        for key, values in alignment.items():
+            require(all(value == values[0] for value in values), label + str(key) + ': states/frames must share canvas, pivot and logical size')
+        audio_ids = set()
+        actual_sounds = Counter()
+        for sound in sounds:
+            identity = sound.get('id')
+            require(isinstance(identity, str) and bool(identity) and identity not in audio_ids and identity not in ids,
+                    label + 'sound ids must be unique and distinct from images')
+            if not isinstance(identity, str):
+                continue
+            audio_ids.add(identity)
+            key = (sound.get('sound'), sound.get('variant'))
+            if not all(isinstance(v, str) and v for v in key):
+                errors.append(label + identity + ': invalid sound/variant')
+                continue
+            actual_sounds[key] += 1
+            source_path(sound.get('source'), label + identity)
+            if 'wav' in sound:
+                wav = sound['wav']
+                if not isinstance(wav, dict):
+                    errors.append(label + identity + ': wav must be an object')
+                else:
+                    fields = ('sample_rate', 'channels', 'sample_width', 'frames')
+                    require(all(type(wav.get(k)) is int and wav[k] > 0 for k in fields), label + identity + ': WAV format fields must be positive integers')
+                    require(type(wav.get('loop')) is bool, label + identity + ': WAV loop must be Boolean')
+                    file = source_path(wav.get('file'), label + identity + ' WAV')
+                    if file:
+                        try:
+                            with wave.open(str(file), 'rb') as audio:
+                                actual_format = (audio.getframerate(), audio.getnchannels(), audio.getsampwidth(), audio.getnframes())
+                                require(actual_format == tuple(wav.get(k) for k in fields), label + identity + ': WAV header differs from contract')
+                                require(audio.getcomptype() == 'NONE' and audio.getnframes() > 0, label + identity + ': WAV must be nonempty PCM')
+                                expected_bytes = audio.getnframes() * audio.getnchannels() * audio.getsampwidth()
+                                # Stream the data to avoid loading an entire music file into memory.
+                                actual_bytes = 0
+                                while block := audio.readframes(65536):
+                                    actual_bytes += len(block)
+                                require(actual_bytes == expected_bytes, label + identity + ': truncated WAV payload')
+                        except (wave.Error, EOFError, OSError) as error:
+                            errors.append(label + identity + ': unreadable WAV: ' + str(error))
+            require(isinstance(sound.get('reference'), str) and bool(sound['reference']), label + identity + ': recipe/pattern reference required')
+            require(sound.get('kind') in ('effect', 'sustained', 'music', 'ambient', 'ui'), label + identity + ': unknown sound kind')
+            require(isinstance(sound.get('design'), dict) and bool(sound['design']), label + identity + ': sound design required')
+            require(isinstance(sound.get('provenance'), dict) and bool(sound['provenance']), label + identity + ': sound provenance required')
+        require(actual_sounds == expected_sounds, label + 'sound contract incomplete or contains unexpected/duplicate variants')
+        aliases = group.get('aliases', {})
+        require(isinstance(aliases, dict), label + 'aliases must be an object')
+        if isinstance(aliases, dict):
+            for alias, target in aliases.items():
+                require(alias not in ids | audio_ids and isinstance(target, str) and target in ids | audio_ids,
+                        label + alias + ': alias must directly reference an existing asset or sound without masking an id')
+        layers = group.get('parallax', [])
+        require(isinstance(layers, list), label + 'parallax must be a list')
+        if layers or contract.get('parallax'):
+            require(isinstance(layers, list) and len(layers) == 3 and {layer.get('depth') for layer in layers} == {'far', 'middle', 'near'},
+                    label + 'parallax requires far, middle and near layers')
+            if isinstance(layers, list):
+                layer_assets = [layer.get('asset') for layer in layers]
+                require(len(set(layer_assets)) == 3, label + 'parallax layers must be independent assets')
+                orders = {}
+                for layer in layers:
+                    asset = asset_by_id.get(layer.get('asset'))
+                    require(bool(asset) and asset.get('family') == 'backgrounds', label + 'parallax references unknown/non-background asset')
+                    require(type(layer.get('transparent')) is bool and asset is not None and asset.get('transparency') == layer.get('transparent'),
+                            label + 'parallax transparency must match its asset')
+                    require(layer.get('repeat') in ('none', 'x', 'y', 'xy'), label + 'invalid parallax repeat')
+                    require(numbers(layer.get('displacement'), 2), label + 'parallax displacement must be finite x/y')
+                    order = layer.get('order')
+                    require(type(order) is int, label + 'parallax order must be integer')
+                    orders[layer.get('depth')] = order
+                if all(type(orders.get(k)) is int for k in ('far', 'middle', 'near')):
+                    require(orders['far'] < orders['middle'] < orders['near'], label + 'parallax orders must increase with depth')
+        for event in group.get('events', []):
+            require(isinstance(event.get('event'), str) and bool(event['event']), label + 'semantic event required')
+            require(event.get('visual') in ids and event.get('sound') in audio_ids, label + 'event references unknown visual/sound')
+            require(event.get('timing') in ('discrete', 'sustained', 'music'), label + 'event timing must be discrete, sustained or music (never each frame)')
+        counts.append({'set': name, 'contract': group.get('contract'), 'unique_resources': len({k[0] for k in actual}),
+                       'png_frames': len(assets), 'sound_variants': len(sounds), 'aliases': len(aliases)})
+    return errors, counts
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('manifest', type=Path)
+    parser.add_argument('--root', type=Path, help='source root; defaults to manifest directory')
+    args = parser.parse_args()
+    try:
+        data = json.loads(args.manifest.read_text(encoding='utf-8'))
+        if not isinstance(data, dict):
+            raise ValueError('manifest must be an object')
+        errors, counts = validate(data, args.root or args.manifest.parent)
+    except (ValueError, OSError, TypeError, KeyError, AttributeError) as error:
+        errors, counts = ['malformed manifest: ' + str(error)], []
+    print(json.dumps({'valid': not errors, 'counts': counts, 'errors': errors}, indent=2))
+    raise SystemExit(1 if errors else 0)
+
+
+if __name__ == '__main__':
+    main()