clipwright-wrap 0.1.0__tar.gz

clipwright_wrap-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.3
+Name: clipwright-wrap
+Version: 0.1.0
+Summary: MCP tool to format subtitle file (SRT/VTT) text at phrase boundaries with line wrapping using BudouX.
+Author: satoh-y-0323
+Author-email: satoh-y-0323 <shoma.papa.0323@gmail.com>
+License: MIT
+Requires-Dist: budoux
+Requires-Dist: clipwright>=0.1.0
+Requires-Dist: mcp[cli]>=1.27.2
+Requires-Dist: pydantic>=2
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# clipwright-wrap
+
+MCP tool to format subtitle file text (SRT/VTT) at phrase boundaries using BudouX with line wrapping.
+
+## Overview
+
+`clipwright-wrap` takes SRT/VTT subtitle files as input, splits each cue text into phrase units by BudouX, inserts line breaks to fit within specified character count and line count, and outputs the subtitle file in the same format. A pure text formatting tool with no FFmpeg / Whisper dependencies.
+
+## Input/Output
+
+- **Input**: SRT file (`.srt`) or VTT file (`.vtt`)
+- **Output**: Subtitle file in same format as input (with phrase boundary line breaks inserted)
+- **Timecodes**: Unchanged (no retiming)
+
+## MCP Tool
+
+`clipwright_wrap_captions`
+
+### Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `input` | `string` | required | Input subtitle file path (`.srt` / `.vtt`) |
+| `output` | `string` | required | Output subtitle file path (same extension as input) |
+| `language` | `string` | `"ja"` | Phrase splitting language (`ja` / `zh-hans` / `zh-hant` / `th`) |
+| `max_chars` | `int` | `16` | Max characters per line (full-width and half-width both count as 1 character). Positive integer. |
+| `max_lines` | `int` | `2` | Max lines per cue. Over-limit cues recorded in warnings (not truncated). Positive integer. |
+
+### Character Count Specification
+
+`max_chars` is **counted uniformly as 1 character each** (both full-width and half-width as one `len()` character). Full-width normalization is a future extension (requirement §8).
+
+## Phrase Wrapping Mechanism
+
+1. Each cue text (if multiple lines, remove line breaks and concatenate) is split into phrases by BudouX
+2. Phrase token sequence is greedily packed into one line within `max_chars`
+3. Formatted text (multiple lines separated by `\n`) is written back to cue
+
+If a single phrase exceeds `max_chars` alone, place that phrase on one line (no splitting mid-phrase).
+
+## Supported Languages
+
+Supports the following languages for which BudouX provides phrase splitting:
+
+| `language` Value | Language |
+|---|---|
+| `ja` | Japanese |
+| `zh-hans` | Chinese (Simplified) |
+| `zh-hant` | Chinese (Traditional) |
+| `th` | Thai |
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `budoux` | Phrase boundary splitting (standard dependency, lightweight model bundled) |
+| `clipwright` | Shared types, envelope, errors |
+| `mcp[cli]` | MCP server |
+| `pydantic` | Parameter validation |
+
+**No FFmpeg / Whisper dependencies** (pure text formatting). `budoux` is a standard dependency bundled with the package, so e2e tests can run continuously without environment variable gating.
+
+## Installation and Startup
+
+```bash
+uv add clipwright-wrap
+clipwright-wrap
+```
+
+Or within a uv workspace:
+
+```bash
+uv run --package clipwright-wrap clipwright-wrap
+```
+
+## Prerequisites
+
+- Python 3.11 or later
+- FFmpeg not required (text formatting only)

clipwright_wrap-0.1.0/README.md

@@ -0,0 +1,79 @@
+# clipwright-wrap
+
+MCP tool to format subtitle file text (SRT/VTT) at phrase boundaries using BudouX with line wrapping.
+
+## Overview
+
+`clipwright-wrap` takes SRT/VTT subtitle files as input, splits each cue text into phrase units by BudouX, inserts line breaks to fit within specified character count and line count, and outputs the subtitle file in the same format. A pure text formatting tool with no FFmpeg / Whisper dependencies.
+
+## Input/Output
+
+- **Input**: SRT file (`.srt`) or VTT file (`.vtt`)
+- **Output**: Subtitle file in same format as input (with phrase boundary line breaks inserted)
+- **Timecodes**: Unchanged (no retiming)
+
+## MCP Tool
+
+`clipwright_wrap_captions`
+
+### Parameters
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `input` | `string` | required | Input subtitle file path (`.srt` / `.vtt`) |
+| `output` | `string` | required | Output subtitle file path (same extension as input) |
+| `language` | `string` | `"ja"` | Phrase splitting language (`ja` / `zh-hans` / `zh-hant` / `th`) |
+| `max_chars` | `int` | `16` | Max characters per line (full-width and half-width both count as 1 character). Positive integer. |
+| `max_lines` | `int` | `2` | Max lines per cue. Over-limit cues recorded in warnings (not truncated). Positive integer. |
+
+### Character Count Specification
+
+`max_chars` is **counted uniformly as 1 character each** (both full-width and half-width as one `len()` character). Full-width normalization is a future extension (requirement §8).
+
+## Phrase Wrapping Mechanism
+
+1. Each cue text (if multiple lines, remove line breaks and concatenate) is split into phrases by BudouX
+2. Phrase token sequence is greedily packed into one line within `max_chars`
+3. Formatted text (multiple lines separated by `\n`) is written back to cue
+
+If a single phrase exceeds `max_chars` alone, place that phrase on one line (no splitting mid-phrase).
+
+## Supported Languages
+
+Supports the following languages for which BudouX provides phrase splitting:
+
+| `language` Value | Language |
+|---|---|
+| `ja` | Japanese |
+| `zh-hans` | Chinese (Simplified) |
+| `zh-hant` | Chinese (Traditional) |
+| `th` | Thai |
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `budoux` | Phrase boundary splitting (standard dependency, lightweight model bundled) |
+| `clipwright` | Shared types, envelope, errors |
+| `mcp[cli]` | MCP server |
+| `pydantic` | Parameter validation |
+
+**No FFmpeg / Whisper dependencies** (pure text formatting). `budoux` is a standard dependency bundled with the package, so e2e tests can run continuously without environment variable gating.
+
+## Installation and Startup
+
+```bash
+uv add clipwright-wrap
+clipwright-wrap
+```
+
+Or within a uv workspace:
+
+```bash
+uv run --package clipwright-wrap clipwright-wrap
+```
+
+## Prerequisites
+
+- Python 3.11 or later
+- FFmpeg not required (text formatting only)

clipwright_wrap-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "clipwright-wrap"
+version = "0.1.0"
+description = "MCP tool to format subtitle file (SRT/VTT) text at phrase boundaries with line wrapping using BudouX."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "satoh-y-0323", email = "shoma.papa.0323@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "budoux",
+    "clipwright>=0.1.0",
+    "mcp[cli]>=1.27.2",
+    "pydantic>=2",
+]
+
+[project.scripts]
+clipwright-wrap = "clipwright_wrap.server:main"
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "clipwright-transcribe",
+    "mypy>=2.1.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.15.16",
+]
+
+# Resolve clipwright (core) and clipwright-transcribe within workspace by path reference
+[tool.uv.sources]
+clipwright = { workspace = true }
+clipwright-transcribe = { workspace = true }
+
+# --- Ruff ---
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM"]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+# Allow E501 for English docstrings/comments in test files
+"tests/*.py" = ["E501"]
+
+[tool.ruff.format]
+# Default ruff formatter is OK
+
+# --- mypy ---
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_any_generics = true
+
+# budoux has no stubs, ignored with mypy strict
+[[tool.mypy.overrides]]
+module = "budoux.*"
+ignore_missing_imports = true
+
+# --- pytest ---
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers -q"
+markers = [
+    "integration: integration test requiring actual ffmpeg/ffprobe binaries",
+    "slow: test with long execution time",
+]
+
+# --- coverage ---
+[tool.coverage.run]
+source = ["clipwright_wrap"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false

clipwright_wrap-0.1.0/src/clipwright_wrap/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

clipwright_wrap-0.1.0/src/clipwright_wrap/captions.py

@@ -0,0 +1,383 @@
+"""captions.py — clipwright-wrap pure-logic layer.
+
+Handles SRT/VTT parsing, greedy line-filling of phrase-boundary token sequences
+with max_chars, SRT/VTT re-serialisation, and overflow detection.
+Pure functions with no budoux import (contract coverage target: ~100%).
+
+Design decisions:
+- Timecode strings are preserved as-is without float conversion (WR-AD-06).
+- SRT/VTT byte structure conforms to the WR-AD-12 specification.
+- No delimiter is inserted when joining phrase-boundary tokens (WR-AD-14).
+- Overflow detection covers both line-count excess (a) and line-width excess (b)
+  (WR-AD-15(1)).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TypedDict
+
+from clipwright.errors import ClipwrightError, ErrorCode
+
+# Regex matching a VTT timeline line: "HH:MM:SS.mmm --> HH:MM:SS.mmm [settings]"
+_VTT_TIMELINE_RE = re.compile(
+    r"^(\d{2}:\d{2}:\d{2}\.\d{3})\s+-->\s+(\d{2}:\d{2}:\d{2}\.\d{3})(.*)"
+)
+
+# Regex matching an SRT timeline line: "HH:MM:SS,mmm --> HH:MM:SS,mmm"
+# Fixed-width HH:MM:SS,mmm digits; conforms to WR-AD-12
+# (transcribe to_srt guarantees fixed width)
+_SRT_TIMELINE_RE = re.compile(
+    r"^(\d{2}:\d{2}:\d{2},\d{3})\s+-->\s+(\d{2}:\d{2}:\d{2},\d{3})\s*$"
+)
+
+# Detection of VTT inline tags (<c>, <b>, <i>, <v>, <ruby>, etc.)
+# The [^>]{0,200} upper bound mitigates ReDoS (CWE-1333)
+_VTT_INLINE_TAG_RE = re.compile(r"<[a-zA-Z/][^>]{0,200}>")
+
+
+@dataclass
+class Cue:
+    """Normalised representation of a single subtitle cue.
+
+    index is the sequence number (1-based).
+    start / end are timecode strings (not converted to float; WR-AD-06).
+    text is the cue body text (line breaks represented as '\\n').
+    VTT cue settings are appended to the end field
+    (e.g. "00:00:01.000 line:90% position:50%").
+    """
+
+    index: int
+    start: str
+    end: str
+    text: str
+
+
+class _OverflowResult(TypedDict):
+    """Return type of check_overflow."""
+
+    line_count_overflow: bool
+    line_width_overflow: bool
+
+
+def _parse_srt(text: str) -> list[Cue]:
+    """Convert an SRT text string into a list of Cues.
+
+    Conforms to the WR-AD-12(1)(2) byte-structure specification:
+    - Blank-line delimited (robust to consecutive / trailing blank lines)
+    - Does not miss the last cue when the trailing cue has no blank line
+      (single newline EOF)
+    - 0 entries (empty string or newlines only) → []
+    - Multi-line text within a cue is joined without a delimiter
+      (no space inserted; WR-AD-14)
+    - Invalid timecode line → raises ValueError
+      (caller wrap.py converts this to INVALID_INPUT)
+    """
+    if not text.strip():
+        return []
+
+    # Normalise consecutive blank lines to a single blank line before splitting
+    normalized = re.sub(r"\n{2,}", "\n\n", text.strip())
+    blocks = normalized.split("\n\n")
+
+    cues: list[Cue] = []
+    for block in blocks:
+        lines = block.strip().splitlines()
+        if not lines:  # pragma: no cover
+            # Unreachable: normalisation never produces an empty block (defensive guard)
+            continue
+
+        # Line 1: index number
+        try:
+            index = int(lines[0].strip())
+        except ValueError:
+            # Block does not start with an index line; skip (empty block, etc.)
+            continue
+
+        if len(lines) < 2:
+            continue
+
+        # Line 2: timeline line
+        timeline_line = lines[1].strip()
+        m = _SRT_TIMELINE_RE.match(timeline_line)
+        if m is None:
+            # Invalid timecode line: raise ValueError (test contract WR-AD-09)
+            raise ValueError(
+                f"Invalid SRT timecode line: {timeline_line!r}"
+                f" (expected format: 'HH:MM:SS,mmm --> HH:MM:SS,mmm')"
+            )
+
+        start = m.group(1)
+        end = m.group(2)
+
+        # Value range check: MM/SS must be within 0–59 (WR-AD-12 / SRT spec)
+        for tc in (start, end):
+            mm, ss = int(tc[3:5]), int(tc[6:8])
+            if mm > 59 or ss > 59:
+                raise ValueError(
+                    f"SRT timecode value out of range: {tc!r}"
+                    f" (minutes and seconds must be within 0–59)"
+                )
+
+        # Line 3 onwards: text (multiple lines joined without delimiter; no space)
+        text_lines = lines[2:] if len(lines) > 2 else []
+        joined_text = "".join(text_lines)
+
+        cues.append(Cue(index=index, start=start, end=end, text=joined_text))
+
+    return cues
+
+
+def _parse_vtt(text: str) -> list[Cue]:
+    """Convert a VTT text string into a list of Cues.
+
+    Conforms to the WR-AD-12(1)(2)(3) byte-structure specification
+    and all 5 VTT edge-case behaviours:
+    - Skip the blank line immediately after the WEBVTT header
+    - 0 entries ("WEBVTT\\n" only) → []
+    - NOTE/STYLE blocks: preserved as-is (not treated as cues)
+    - cue id line: preserved; only the text lines are formatting targets
+    - cue settings (trailing part of the timeline line): appended to the end field
+    - cues containing inline tags: text preserved as-is (tags included, single line)
+    - Multi-line text within a cue is joined without a delimiter (WR-AD-14)
+    """
+    lines = text.splitlines()
+
+    # Verify and skip the WEBVTT header
+    if not lines or not lines[0].startswith("WEBVTT"):
+        return []
+
+    # Process lines after the header
+    pos = 1
+    total = len(lines)
+
+    # Skip blank lines immediately after the header
+    while pos < total and lines[pos].strip() == "":
+        pos += 1
+
+    cues: list[Cue] = []
+    cue_index = 1
+
+    while pos < total:
+        # Skip blank lines (cue separator)
+        if lines[pos].strip() == "":
+            pos += 1
+            continue
+
+        # NOTE block: skip until the next blank line or EOF
+        if lines[pos].startswith("NOTE"):
+            pos += 1
+            while pos < total and lines[pos].strip() != "":
+                pos += 1
+            continue
+
+        # STYLE block: skip until the next blank line or EOF
+        if lines[pos].startswith("STYLE"):
+            pos += 1
+            while pos < total and lines[pos].strip() != "":
+                pos += 1
+            continue
+
+        # Check for a cue id line (non-empty line that is not a timeline line)
+        if not _VTT_TIMELINE_RE.match(lines[pos]):
+            # cue id line: identifier before the timeline — skip (preserved implicitly)
+            pos += 1
+            if pos >= total:
+                break
+
+        # Timeline line
+        if pos >= total or lines[pos].strip() == "":
+            pos += 1
+            continue
+
+        m = _VTT_TIMELINE_RE.match(lines[pos])
+        if m is None:  # pragma: no cover
+            # Unreachable for well-formed VTT input (fallback defensive guard)
+            pos += 1
+            continue
+
+        start = m.group(1)
+        # Append settings to end field for preservation (WR-AD-12(3)(d))
+        end_raw = m.group(2)
+        settings = m.group(3).strip()
+        end = f"{end_raw} {settings}" if settings else end_raw
+
+        pos += 1
+
+        # Collect text lines until the next blank line or EOF
+        text_lines: list[str] = []
+        while pos < total and lines[pos].strip() != "":
+            text_lines.append(lines[pos])
+            pos += 1
+
+        # Join text without a delimiter (no space inserted; WR-AD-14)
+        joined_text = "".join(text_lines)
+
+        cues.append(Cue(index=cue_index, start=start, end=end, text=joined_text))
+        cue_index += 1
+
+    return cues
+
+
+def parse_captions(text: str, fmt: str) -> list[Cue]:
+    """Convert an SRT or VTT text string into a list of Cues.
+
+    fmt must be "srt" or "vtt".
+    Timecode strings are preserved as-is (WR-AD-06).
+    Multi-line text within a cue is joined without a delimiter (WR-AD-14).
+    An invalid timecode line causes _parse_srt to raise ValueError,
+    which wrap.py converts to ClipwrightError(INVALID_INPUT) (WR-AD-09).
+
+    Args:
+        text: SRT or VTT format string.
+        fmt: "srt" or "vtt".
+
+    Returns:
+        List of Cues. Returns an empty list when there are 0 entries.
+    """
+    if fmt == "srt":
+        return _parse_srt(text)
+    elif fmt == "vtt":
+        return _parse_vtt(text)
+    else:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=f"Unsupported subtitle format: {fmt!r}",
+            hint="Specify 'srt' or 'vtt' for fmt.",
+        )
+
+
+def wrap_cue_lines(segments: list[str], max_chars: int) -> list[str]:
+    """Return lines formed by greedily packing phrase-boundary tokens up to max_chars.
+
+    Conforms to WR-AD-04/WR-AD-14:
+    - Segments are appended to a line; a line break is inserted just before the
+      limit is exceeded (greedy fill).
+    - If a single segment exceeds max_chars on its own, it is placed on its own
+      line without splitting.
+    - No delimiter is inserted between segments
+      (WR-AD-14(i); joining lines restores the original text).
+    - '\\n' is not included in len() of each line (WR-AD-14(ii)).
+    - Full-width and half-width characters are each counted as 1
+      (WR-AD-14(iii); uniform len() check).
+
+    Args:
+        segments: List of phrase-boundary tokens.
+        max_chars: Maximum number of characters per line (gt=0).
+
+    Returns:
+        List of lines (no '\\n' within any line). Returns [] for empty segments.
+    """
+    if not segments:
+        return []
+
+    lines: list[str] = []
+    current_line = ""
+
+    for seg in segments:
+        if not current_line:
+            # Start of a line: place segment even if exceeds max_chars (no splitting)
+            current_line = seg
+        elif len(current_line) + len(seg) <= max_chars:
+            # Adding the segment stays within max_chars → append to the same line
+            current_line += seg
+        else:
+            # Would exceed the limit → insert a line break
+            lines.append(current_line)
+            current_line = seg
+
+    if current_line:
+        lines.append(current_line)
+
+    return lines
+
+
+def _serialize_srt(cues: list[Cue]) -> str:
+    """Convert a list of Cues into an SRT string.
+
+    Byte-structure specification (WR-AD-12(1)):
+    - Each block = "index\\nstart --> end\\ntext\\n"
+    - One blank line between cues (trailing \\n of the block + the join \\n)
+    - Single newline after the last cue (no trailing blank line)
+    - 0 entries → ""
+    """
+    if not cues:
+        return ""
+
+    blocks: list[str] = []
+    for cue in cues:
+        blocks.append(f"{cue.index}\n{cue.start} --> {cue.end}\n{cue.text}\n")
+
+    return "\n".join(blocks)
+
+
+def _serialize_vtt(cues: list[Cue]) -> str:
+    """Convert a list of Cues into a VTT string.
+
+    Byte-structure specification (WR-AD-12(1)):
+    - "WEBVTT\\n" + "\\n" + cue1 + "\\n" + cue2 + ...
+    - Each cue block = "start --> end\\ntext\\n"
+    - One blank line between cues; single newline after the last cue
+      (no trailing blank line)
+    - 0 entries → "WEBVTT\\n"
+    """
+    if not cues:
+        return "WEBVTT\n"
+
+    blocks: list[str] = ["WEBVTT\n"]
+    for cue in cues:
+        blocks.append(f"{cue.start} --> {cue.end}\n{cue.text}\n")
+
+    return "\n".join(blocks)
+
+
+def serialize_captions(cues: list[Cue], fmt: str) -> str:
+    """Convert a list of Cues into an SRT or VTT string.
+
+    Timecode strings are written back unchanged (WR-AD-06).
+    For 0 entries: SRT → "" / VTT → "WEBVTT\\n" (round-trip identity; WR-AD-12(2)).
+
+    Args:
+        cues: List of Cues.
+        fmt: "srt" or "vtt".
+
+    Returns:
+        SRT or VTT format string.
+    """
+    if fmt == "srt":
+        return _serialize_srt(cues)
+    elif fmt == "vtt":
+        return _serialize_vtt(cues)
+    else:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=f"Unsupported subtitle format: {fmt!r}",
+            hint="Specify 'srt' or 'vtt' for fmt.",
+        )
+
+
+def check_overflow(lines: list[str], max_chars: int, max_lines: int) -> _OverflowResult:
+    """Detect overflow (line-count excess and line-width excess) in a list of lines.
+
+    Overflow detection specification (WR-AD-15(1)):
+    - (a) len(lines) > max_lines → line_count_overflow: True
+    - (b) any line's len() > max_chars → line_width_overflow: True
+    A single oversized segment (1 line, width excess) is also covered by (b).
+    lines is not modified (avoids information loss).
+
+    Args:
+        lines: List of lines to inspect (each line must not contain '\\n').
+        max_chars: Maximum number of characters per line.
+        max_lines: Maximum number of lines.
+
+    Returns:
+        Dict with line_count_overflow and line_width_overflow keys.
+    """
+    line_count_overflow = len(lines) > max_lines
+    line_width_overflow = any(len(line) > max_chars for line in lines)
+
+    return {
+        "line_count_overflow": line_count_overflow,
+        "line_width_overflow": line_width_overflow,
+    }

clipwright_wrap-0.1.0/src/clipwright_wrap/schemas.py

@@ -0,0 +1,71 @@
+"""schemas.py — clipwright-wrap-specific Pydantic schemas.
+
+Common types (MediaRef / Artifact / ToolResult, etc.) are defined
+centrally in clipwright.schemas; this module does not redefine them.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+
+class WrapCaptionsOptions(BaseModel):
+    """Options for clipwright_wrap_captions (WR-AD-05).
+
+    language selects the budoux parser.
+    All 4 languages confirmed loadable in spike-budoux (DC-AM-005).
+    max_chars is the maximum number of characters per line
+    (each character counts as 1; len() check).
+    max_lines is the maximum number of lines per cue
+    (excess is subject to warnings; WR-AD-15(1)).
+    """
+
+    language: Annotated[
+        str,
+        Field(
+            default="ja",
+            max_length=7,
+            pattern=r"^(ja|zh-hans|zh-hant|th)$",
+            description=(
+                "Language code to select the budoux phrase-boundary parser. "
+                "Supported languages: ja / zh-hans / zh-hant / th. "
+                "All 4 languages confirmed in spike-budoux (DC-AM-005). "
+                "Unsupported values are rejected with INVALID_INPUT."
+            ),
+        ),
+    ] = "ja"
+
+    max_chars: Annotated[
+        int,
+        Field(
+            default=16,
+            gt=0,
+            description=(
+                "Maximum number of characters per line"
+                " (each character counts as 1; len() check). "
+                "Default is ~16 full-width characters, following"
+                " Japanese subtitle conventions (WR-AD-05). "
+                "A line break is inserted just before the limit is exceeded"
+                " (greedy fill; WR-AD-04). "
+                "If a single phrase segment exceeds the limit on its own,"
+                " it is placed on one line without splitting. "
+                "gt=0 constraint: 0 or below is rejected with INVALID_INPUT."
+            ),
+        ),
+    ] = 16
+
+    max_lines: Annotated[
+        int,
+        Field(
+            default=2,
+            gt=0,
+            description=(
+                "Maximum number of lines per cue. Excess is recorded in warnings. "
+                "The original text is preserved without truncation"
+                " (WR-AD-15(1); requirement §2). "
+                "gt=0 constraint: 0 or below is rejected with INVALID_INPUT."
+            ),
+        ),
+    ] = 2

clipwright_wrap-0.1.0/src/clipwright_wrap/server.py

@@ -0,0 +1,90 @@
+"""server.py — clipwright-wrap MCP server + CLI entry point.
+
+A thin wrapper that delegates business logic to wrap.py.
+ClipwrightError conversion and language validation are handled by wrap.py / schemas.py,
+so this module does not perform double conversion (DC-GP-001).
+
+Transport defaults to stdio (mcp.run(transport="stdio")).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from clipwright_wrap.schemas import WrapCaptionsOptions
+from clipwright_wrap.wrap import wrap_captions
+
+# FastMCP instance (server name)
+mcp = FastMCP("clipwright-wrap")
+
+
+# ===========================================================================
+# clipwright_wrap_captions MCP tool
+# ===========================================================================
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    )
+)
+def clipwright_wrap_captions(
+    input: Annotated[
+        str,
+        Field(description="Input subtitle file path (.srt or .vtt)."),
+    ],
+    output: Annotated[
+        str,
+        Field(description="Output subtitle file path (same extension as input)."),
+    ],
+    options: Annotated[
+        WrapCaptionsOptions | None,
+        Field(
+            description=(
+                "Phrase-boundary line-break options"
+                " (language / max_chars / max_lines). "
+                "When omitted, all defaults are used"
+                " (language='ja' / max_chars=16 / max_lines=2)."
+            )
+        ),
+    ] = None,
+) -> dict[str, Any]:
+    """MCP tool: insert phrase-boundary line breaks into a subtitle file.
+
+    The input subtitle file is never modified (non-destructive; readOnly).
+    The output is the path of the newly generated SRT/VTT, returned in artifacts.
+
+    Business logic is delegated to wrap.wrap_captions.
+    When options is None, the default WrapCaptionsOptions() is used.
+    """
+    resolved_options = options if options is not None else WrapCaptionsOptions()
+    return wrap_captions(
+        input=input,
+        output=output,
+        options=resolved_options,
+    )
+
+
+# ===========================================================================
+# Entry point (MCP stdio launch)
+# ===========================================================================
+
+
+def main() -> None:
+    """CLI entry point. Launches the MCP server over stdio.
+
+    Registered in pyproject.toml [project.scripts] as
+    clipwright-wrap = "clipwright_wrap.server:main".
+    """
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

clipwright_wrap-0.1.0/src/clipwright_wrap/wrap.py

@@ -0,0 +1,317 @@
+"""wrap.py — clipwright-wrap orchestration layer.
+
+Output validation → input existence check → subtitle parsing →
+wrap_cli launch (phrase segmentation) →
+greedy line-filling and re-serialisation via captions → output write → envelope return.
+
+Design decisions:
+- wrap_cli is launched as sys.executable -m clipwright_wrap.wrap_cli (WR-AD-01).
+- wrap_cli error detection is based on the "error" key in stdout JSON (DC-AS-007).
+- subprocess failure/timeout uses the sanitised message in _SUBPROCESS_SAFE_MESSAGE.
+- FILE_NOT_FOUND message contains only the basename (no full path exposure; WR-AD-09).
+- Overflow detection covers both line-count excess (a) and line-width excess (b)
+  (WR-AD-15(1)).
+- Warnings use a single aggregated sentence + index arrays in data
+  (WR-AD-13(2); DC-AM-002).
+- artifacts are dicts (Artifact model not instantiated; DC-AS-005).
+- OTIO is neither generated nor used (WR-AD-06).
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from clipwright.envelope import error_result, ok_result
+from clipwright.errors import ClipwrightError, ErrorCode
+
+from clipwright_wrap.captions import (
+    check_overflow,
+    parse_captions,
+    serialize_captions,
+    wrap_cue_lines,
+)
+from clipwright_wrap.schemas import WrapCaptionsOptions
+
+# Sanitised message for subprocess failure/timeout (prevents stderr path leakage)
+_SUBPROCESS_SAFE_MESSAGE = "internal subprocess failed"
+
+# Timeout coefficient proportional to cue count (WR-AD-11/WR-AD-15(2))
+_TIMEOUT_COEFFICIENT = 0.05
+_TIMEOUT_MIN = 30
+
+
+def _compute_timeout(cue_count: int) -> float:
+    """Calculate the cue-count-proportional timeout.
+
+    Returns max(30, ceil(cue_count * 0.05)).
+    """
+    return float(max(_TIMEOUT_MIN, math.ceil(cue_count * _TIMEOUT_COEFFICIENT)))
+
+
+def wrap_captions(
+    input: str,
+    output: str,
+    options: WrapCaptionsOptions,
+) -> dict[str, Any]:
+    """Insert phrase-boundary line breaks into a subtitle file (WR-AD-04).
+
+    Non-destructive: the input subtitle file is never modified.
+    The output is the path of the newly generated SRT/VTT, returned in artifacts.
+
+    Args:
+        input: Input subtitle file path (.srt or .vtt).
+        output: Output subtitle file path (same extension as input).
+        options: WrapCaptionsOptions (language/max_chars/max_lines).
+
+    Returns:
+        Envelope dict as ok_result or error_result.
+    """
+    try:
+        return _wrap_inner(input, output, options)
+    except ClipwrightError as exc:
+        return error_result(exc.code, exc.message, exc.hint)
+
+
+def _wrap_inner(
+    input: str,
+    output: str,
+    options: WrapCaptionsOptions,
+) -> dict[str, Any]:
+    """Internal implementation of wrap_captions. Raises ClipwrightError directly."""
+    input_path = Path(input)
+    output_path = Path(output)
+
+    # --- 1. Output validation (WR-AD-07/08) ---
+
+    # Verify that extensions are srt/vtt
+    input_ext = input_path.suffix.lower()
+    output_ext = output_path.suffix.lower()
+
+    if input_ext not in (".srt", ".vtt"):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=f"Unsupported subtitle format: {input_ext!r}",
+            hint="Set the input file extension to .srt or .vtt.",
+        )
+
+    if output_ext not in (".srt", ".vtt"):
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=f"Unsupported output extension: {output_ext!r}",
+            hint="Set the output file extension to .srt or .vtt.",
+        )
+
+    # Verify extensions match (SRT↔VTT cross-conversion is out of scope)
+    if input_ext != output_ext:
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message=(
+                f"Input and output extensions do not match"
+                f" (input: {input_ext!r} / output: {output_ext!r})."
+            ),
+            hint="Specify an output path with the same extension as the input.",
+        )
+
+    # Verify that the output parent directory exists
+    if not output_path.parent.exists():
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Output directory does not exist.",
+            hint="Create the output directory first, then run again.",
+        )
+
+    # Prohibit output == input
+    try:
+        if output_path.resolve() == input_path.resolve():
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message="Output path and input path are the same.",
+                hint="Change the output file path to a path different from the input.",
+            )
+    except OSError:  # pragma: no cover
+        if str(output_path) == str(input_path):
+            raise ClipwrightError(
+                code=ErrorCode.INVALID_INPUT,
+                message="Output path and input path are the same.",
+                hint="Change the output file path to a path different from the input.",
+            ) from None
+
+    # --- 2. Input existence check (WR-AD-09; FILE_NOT_FOUND uses basename only) ---
+
+    if not input_path.exists():
+        raise ClipwrightError(
+            code=ErrorCode.FILE_NOT_FOUND,
+            message=f"File not found: {input_path.name}",
+            hint="Check that the input file path is correct.",
+        )
+
+    # --- 3. Read input ---
+
+    raw_text = input_path.read_text(encoding="utf-8")
+    fmt = input_ext.lstrip(".")  # "srt" or "vtt"
+
+    # --- 4. captions.parse_captions (invalid timecode → INVALID_INPUT + hint) ---
+
+    try:
+        cues = parse_captions(raw_text, fmt)
+    except ValueError:
+        # Convert ValueError to INVALID_INPUT; fixed message (not str(exc)); CWE-209
+        raise ClipwrightError(
+            code=ErrorCode.INVALID_INPUT,
+            message="Failed to parse subtitle file (timecode format error).",
+            hint=(
+                "Check the format of the timecode line"
+                " (e.g. 00:00:00,000 --> 00:00:01,000)."
+            ),
+        ) from None
+
+    # --- 5. Launch wrap_cli (WR-AD-02; DC-AS-007) ---
+
+    cue_count = len(cues)
+    # For 0 entries, skip wrap_cli and serialise directly
+    if cue_count > 0:
+        stdin_payload = json.dumps(
+            {
+                "language": options.language,
+                "texts": [cue.text for cue in cues],
+            },
+            ensure_ascii=False,
+        )
+        timeout = _compute_timeout(cue_count)
+
+        try:
+            proc = subprocess.run(
+                [sys.executable, "-m", "clipwright_wrap.wrap_cli"],
+                input=stdin_payload,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired:
+            raise ClipwrightError(
+                code=ErrorCode.SUBPROCESS_TIMEOUT,
+                message=f"{_SUBPROCESS_SAFE_MESSAGE} (timeout)",
+                hint=(
+                    "The subtitle file may contain too many cues. "
+                    "Try again or reduce the number of cues."
+                ),
+            ) from None
+        except OSError:
+            raise ClipwrightError(
+                code=ErrorCode.SUBPROCESS_FAILED,
+                message=_SUBPROCESS_SAFE_MESSAGE,
+                hint=(
+                    "Failed to launch wrap_cli. "
+                    "Check that clipwright-wrap is correctly installed."
+                ),
+            ) from None
+
+        # wrap_cli returns 0; errors detected via "error" key in stdout JSON (DC-AS-007)
+        try:
+            parsed: dict[str, Any] = json.loads(proc.stdout)
+        except (json.JSONDecodeError, ValueError):
+            raise ClipwrightError(
+                code=ErrorCode.SUBPROCESS_FAILED,
+                message=_SUBPROCESS_SAFE_MESSAGE,
+                hint="Failed to parse wrap_cli output JSON. Please run again.",
+            ) from None
+
+        if "error" in parsed:
+            err = parsed["error"]
+            code_str: str = err.get("code", str(ErrorCode.INTERNAL))
+            msg: str = err.get("message", "An error occurred in wrap_cli")
+            hint: str = err.get("hint", "Please report with reproduction steps.")
+            # Convert to ErrorCode (DEPENDENCY_MISSING propagated as-is)
+            try:
+                code = ErrorCode(code_str)
+            except ValueError:
+                code = ErrorCode.INTERNAL
+            raise ClipwrightError(code=code, message=msg, hint=hint)
+
+        segments: list[list[str]] = parsed.get("segments", [])
+    else:
+        segments = []
+
+    # --- 6. Apply wrap_cue_lines to each cue → overflow detection ---
+
+    overflow_cue_indices: list[int] = []
+    overflow_width_cue_indices: list[int] = []
+    wrapped_count = 0
+
+    for i, cue in enumerate(cues):
+        seg = segments[i] if i < len(segments) else [cue.text]
+        lines = wrap_cue_lines(seg, options.max_chars)
+
+        # Increment wrapped_count when the text has changed (line break inserted)
+        new_text = "\n".join(lines)
+        if new_text != cue.text:
+            wrapped_count += 1
+
+        # Overflow detection (WR-AD-15(1))
+        overflow = check_overflow(lines, options.max_chars, options.max_lines)
+        if overflow["line_count_overflow"]:
+            overflow_cue_indices.append(i)
+        if overflow["line_width_overflow"]:
+            overflow_width_cue_indices.append(i)
+
+        # Update cue.text to the formatted text (no truncation; full text preserved)
+        cue.text = new_text
+
+    # --- 7. captions.serialize_captions → write output ---
+
+    serialized = serialize_captions(cues, fmt)
+    output_path.write_text(serialized, encoding="utf-8")
+
+    # --- 8. Build envelope (WR-AD-13) ---
+
+    warnings: list[str] = []
+
+    # Line-count overflow warnings (aggregated; omitted when 0 entries; DC-AM-002)
+    if overflow_cue_indices:
+        warnings.append(
+            f"{len(overflow_cue_indices)} cue(s) exceeded max_lines"
+            f" ({options.max_lines})"
+            " (see data.overflow_cue_indices for indices)."
+            " Output without truncation to avoid information loss."
+        )
+
+    # Line-width overflow warnings (single aggregated sentence; omitted when 0 entries)
+    if overflow_width_cue_indices:
+        warnings.append(
+            f"{len(overflow_width_cue_indices)} cue(s) exceeded max_chars"
+            f" ({options.max_chars})"
+            " (see data.overflow_width_cue_indices for indices)."
+            " Output without truncation to avoid information loss."
+        )
+
+    total_overflow = len(set(overflow_cue_indices) | set(overflow_width_cue_indices))
+    summary = (
+        f"Phrase-boundary line breaks applied to {cue_count} cue(s)"
+        f" ({wrapped_count} cue(s) had line breaks inserted;"
+        f" {total_overflow} cue(s) exceeded limits)."
+        f" Language: {options.language}."
+        f" Generated {output_path.name}."
+    )
+
+    artifacts = [
+        {"role": "captions", "path": str(output_path), "format": fmt},
+    ]
+
+    return ok_result(
+        summary,
+        data={
+            "cue_count": cue_count,
+            "wrapped_count": wrapped_count,
+            "overflow_cue_indices": overflow_cue_indices,
+            "overflow_width_cue_indices": overflow_width_cue_indices,
+            "language": options.language,
+        },
+        artifacts=artifacts,
+        warnings=warnings,
+    )

clipwright_wrap-0.1.0/src/clipwright_wrap/wrap_cli.py

@@ -0,0 +1,180 @@
+"""wrap_cli.py — Small CLI for BudouX phrase-boundary segmentation (separate process).
+
+Not imported by the MCP server process (§2.4 subprocess loose coupling).
+wrap.py launches this as sys.executable -m clipwright_wrap.wrap_cli in a subprocess.
+
+CLI contract (WR-AD-02):
+  - stdin: JSON {"language": "ja", "texts": ["cue1", ...]}
+  - stdout: JSON {"segments": [["segment1", "segment2", ...], ...]}
+  - On error stdout: {"error": {"code": str, "message": str, "hint": str}}
+  - main() catches all exceptions at the top level, always outputs JSON to stdout,
+    and returns 0.
+  - stdout contains JSON only. Logs and progress go to stderr.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import traceback
+from typing import Any
+
+from clipwright.errors import ErrorCode
+
+# pip install hint string
+_WRAP_INSTALL_HINT = "Install clipwright-wrap with `pip install clipwright-wrap`."
+
+# Mapping of language → parser load function (DC-AS-002: target for test monkeypatching)
+# budoux is imported at module top level. Because this CLI runs in a separate process,
+# there is no risk of leaking into the server process, and _PARSER_LOADERS must be
+# exposed as a module constant (tests reference it directly).
+# If budoux is not installed, the dict stays empty (main() returns DEPENDENCY_MISSING).
+try:
+    import budoux as _budoux
+
+    _PARSER_LOADERS: dict[str, Any] = {
+        "ja": _budoux.load_default_japanese_parser,
+        "zh-hans": _budoux.load_default_simplified_chinese_parser,
+        "zh-hant": _budoux.load_default_traditional_chinese_parser,
+        "th": _budoux.load_default_thai_parser,
+    }
+except ImportError:
+    _PARSER_LOADERS = {}
+
+
+def _error_output(code: str, message: str, hint: str) -> None:
+    """Output an error JSON to stdout.
+
+    The caller must sanitise any path information before passing it here.
+    """
+    result: dict[str, Any] = {
+        "error": {
+            "code": code,
+            "message": message,
+            "hint": hint,
+        }
+    }
+    print(json.dumps(result, ensure_ascii=False), file=sys.stdout)
+
+
+def main(argv: list[str] | None = None) -> int:  # noqa: ARG001
+    """Entry point for wrap_cli.
+
+    Catches all exceptions at the top level, outputs JSON to stdout,
+    and returns 0 (WR-AD-02).
+
+    Args:
+        argv: Command-line argument list (unused in the current version).
+
+    Returns:
+        Exit code (always 0).
+    """
+    try:
+        # --- Read JSON from stdin ---
+        try:
+            raw = sys.stdin.read()
+            payload: dict[str, Any] = json.loads(raw)
+        except (json.JSONDecodeError, ValueError):
+            _error_output(
+                code=str(ErrorCode.INVALID_INPUT),
+                message="Failed to parse JSON from stdin",
+                hint="Pass a valid JSON object to stdin.",
+            )
+            return 0
+
+        # --- Input validation ---
+        if "language" not in payload:
+            _error_output(
+                code=str(ErrorCode.INVALID_INPUT),
+                message="Missing 'language' key",
+                hint="Include a 'language' key in the stdin JSON.",
+            )
+            return 0
+
+        if "texts" not in payload:
+            _error_output(
+                code=str(ErrorCode.INVALID_INPUT),
+                message="Missing 'texts' key",
+                hint="Include a 'texts' key in the stdin JSON.",
+            )
+            return 0
+
+        language: str = payload["language"]
+        texts = payload["texts"]
+
+        if not isinstance(texts, list):
+            _error_output(
+                code=str(ErrorCode.INVALID_INPUT),
+                message="'texts' must be a list",
+                hint="Set 'texts' in the stdin JSON to a list of strings.",
+            )
+            return 0
+
+        if not all(isinstance(t, str) for t in texts):
+            _error_output(
+                code=str(ErrorCode.INVALID_INPUT),
+                message="Each element of 'texts' must be a string",
+                hint="Set 'texts' in the stdin JSON to a list of strings.",
+            )
+            return 0
+
+        # --- Get the parser loader (DC-AS-002: loaded once, outside the texts loop) ---
+        # If budoux is missing (_PARSER_LOADERS empty), return DEPENDENCY_MISSING
+        # CR L-2: return DEPENDENCY_MISSING + install hint instead of INVALID_INPUT
+        if not _PARSER_LOADERS:
+            _error_output(
+                code=str(ErrorCode.DEPENDENCY_MISSING),
+                message="budoux is not installed",
+                hint=_WRAP_INSTALL_HINT,
+            )
+            return 0
+
+        if language not in _PARSER_LOADERS:
+            _error_output(
+                code=str(ErrorCode.INVALID_INPUT),
+                message="Unsupported language specified",
+                hint=(
+                    "Specify one of the following for language:"
+                    " ja / zh-hans / zh-hant / th."
+                ),
+            )
+            return 0
+
+        # Load the parser once outside the texts loop (DC-AS-002)
+        # ImportError when calling the loader is returned as DEPENDENCY_MISSING
+        try:
+            parser = _PARSER_LOADERS[language]()
+        except ImportError:
+            # SR L-2: str(exc) may contain internal paths; use a fixed message instead
+            _error_output(
+                code=str(ErrorCode.DEPENDENCY_MISSING),
+                message="Failed to import budoux",
+                hint=_WRAP_INSTALL_HINT,
+            )
+            return 0
+
+        # --- Segment each cue text into phrase-boundary tokens ---
+        segments: list[list[str]] = []
+        for text in texts:
+            seg: list[str] = parser.parse(text)
+            segments.append(seg)
+
+        result: dict[str, Any] = {"segments": segments}
+        print(json.dumps(result, ensure_ascii=False), file=sys.stdout)
+        return 0
+
+    except Exception:
+        # Catch all unexpected exceptions and return an error JSON (WR-AD-02)
+        # SR NF-L-1: str(exc) may contain internal paths; use a fixed message instead.
+        # Debug details go to stderr only; must not leak into stdout JSON.
+        traceback.print_exc(file=sys.stderr)
+        _error_output(
+            code=str(ErrorCode.INTERNAL),
+            message="An unexpected error occurred in wrap_cli",
+            hint="Please report with reproduction steps.",
+        )
+        return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())