handoffpack 0.1.0__py3-none-any.whl

handoffpack/__init__.py

@@ -0,0 +1,3 @@
+"""handoffpack — deterministic structured-card codec + guards + MCP translator server."""
+
+__version__ = "0.1.0"

handoffpack/adapter_instructions.py

@@ -0,0 +1,492 @@
+"""Instruction-file adapter: recurring-instruction files -> HP1 instruction cards.
+
+Converts CLAUDE.md / SKILL.md / AGENTS.md style recurring-instruction
+files into HP1 cards, one card per section, fully deterministically:
+
+  (a) deterministic pass — markdown section splitter + per-line rule
+      classification into DO / LIM / BAN slots where unambiguous;
+  (b) ambiguous or nuanced content is marked UNCONVERTED with a reason
+      (nuance guard from handoffpack.guards is applied at section level,
+      conditional-clause detection at line level). Content is NEVER
+      silently dropped: every non-blank source line ends up either in
+      a card slot or inside a verbatim UNCONVERTED block.
+  (c) output = a .hp1 card file + a JSON sidecar report (token
+      before/after via the chars/4 estimator, converted/unconverted
+      section counts, BAN-rule violations found);
+  (d) --check mode — validate an existing .hp1 against source drift
+      (sha256 over newline-normalized source text) and re-parse every
+      embedded HP1 card through the codec.
+
+Reuses handoffpack primitives throughout (codec.assemble_card / parse_card /
+estimate_tokens, guards.validate_ban_field / assess_nuance /
+check_breakeven). No network, no LLM, no new card format.
+
+Known deterministic limitations (documented, not hidden):
+  - only ATX markdown headings ('#'..'######') split sections; setext
+    headings are treated as plain content lines;
+  - imperative-verb detection uses a fixed allowlist; anything outside
+    it is honestly UNCONVERTED rather than guessed.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import codec, guards
+from . import license as hplicense
+
+__all__ = [
+    "split_sections",
+    "classify_line",
+    "convert_text",
+    "render_hp1",
+    "build_report",
+    "convert_file",
+    "check_file",
+    "main",
+]
+
+HPINSTR_HEADER = "#HPINSTR 1.0"
+
+# ---------------------------------------------------------------------------
+# line-level patterns
+# ---------------------------------------------------------------------------
+
+_HEADING = re.compile(r"^(#{1,6})\s+(.*\S)\s*$")
+_SEPARATOR = re.compile(r"^\s*[-=_*─-╿]{3,}\s*$")
+_BULLET = re.compile(r"^\s*(?:[-*+]\s+|\d+[.)]\s*)(.*)$")
+_CODE_FENCE = re.compile(r"^\s*(```|~~~)")
+
+# BAN lead-ins: plain prohibitions. The lead-in itself is stripped so the
+# BAN slot holds the forbidden action only ("Never use emojis" -> "use emojis").
+_BAN_LEAD = re.compile(
+    r"^(?:never|do\s+not|don'?t|no|avoid|forbid(?:den)?[:.]?|"
+    r"금지[:.]?|절대)\s+(.+)$",
+    re.IGNORECASE,
+)
+
+# LIM lead-ins: standing constraints. Kept verbatim as the LIM value.
+_LIM_LEAD = re.compile(
+    r"^(?:always|must|only|limit|max(?:imum)?|min(?:imum)?|keep|use|prefer|"
+    r"stick\s+to|ensure|require[sd]?|restrict)\b",
+    re.IGNORECASE,
+)
+
+# DO: imperative dev verbs (fixed allowlist — outside it, honest UNCONVERTED).
+_DO_VERBS = (
+    "run|read|write|check|test|report|commit|push|pull|review|update|create|"
+    "add|remove|delete|install|build|compile|format|lint|document|verify|"
+    "follow|start|stop|open|close|list|ask|search|grep|fix|refactor|rename|"
+    "move|copy|save|log|measure|validate|parse|generate|return|include|"
+    "prepend|append|state|split"
+)
+_DO_LEAD = re.compile(rf"^(?:{_DO_VERBS})\b", re.IGNORECASE)
+
+# Conditional-clause markers: reuse the guard module's nuance markers so
+# line-level and section-level detection cannot diverge.
+_CONDITIONAL = guards._NUANCE_MARKERS
+
+_HP1_PREFIX = codec.load_legend().get("header", "HP1") + codec.load_legend().get("separator", "|")
+
+_UNCONV_BEGIN = "#--UNCONVERTED"
+_UNCONV_END = "#--END"
+
+
+# ---------------------------------------------------------------------------
+# data model
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Section:
+    index: int
+    title: str
+    heading_line: str | None  # None for preamble
+    lines: list[str] = field(default_factory=list)  # body lines, verbatim
+
+
+@dataclass
+class SectionResult:
+    index: int
+    title: str
+    status: str  # "converted" | "partial" | "unconverted" | "empty"
+    card: str | None
+    slotted: list[tuple[str, str, str]] = field(default_factory=list)  # (line, slot, value)
+    unconverted: list[tuple[str, str]] = field(default_factory=list)  # (line, reason)
+    section_reason: str | None = None
+    ban_violations: list[str] = field(default_factory=list)
+    raw_lines: list[str] = field(default_factory=list)  # heading + body, verbatim
+
+
+@dataclass
+class Conversion:
+    source_name: str
+    source_sha256: str
+    source_text: str
+    sections: list[SectionResult] = field(default_factory=list)
+
+    @property
+    def ban_violations(self) -> list[str]:
+        out: list[str] = []
+        for sec in self.sections:
+            out.extend(sec.ban_violations)
+        return out
+
+
+# ---------------------------------------------------------------------------
+# (a) section splitter
+# ---------------------------------------------------------------------------
+
+def split_sections(text: str) -> list[Section]:
+    """Split instruction text into sections on ATX markdown headings.
+
+    Content before the first heading becomes a "(preamble)" section.
+    Heading lines are kept (heading_line) so nothing is lost when a
+    section must be preserved verbatim.
+    """
+    sections: list[Section] = []
+    current = Section(index=0, title="(preamble)", heading_line=None)
+    for line in text.splitlines():
+        m = _HEADING.match(line)
+        if m:
+            if current.lines or current.heading_line is not None:
+                sections.append(current)
+            current = Section(
+                index=len(sections),
+                title=m.group(2).strip("# ").strip(),
+                heading_line=line,
+            )
+        else:
+            current.lines.append(line)
+    sections.append(current)
+    # drop a fully empty preamble (no content lines at all)
+    if sections and sections[0].heading_line is None and not any(
+        ln.strip() for ln in sections[0].lines
+    ):
+        sections = sections[1:]
+        for i, sec in enumerate(sections):
+            sec.index = i
+    return sections
+
+
+# ---------------------------------------------------------------------------
+# (a)+(b) per-line rule classification
+# ---------------------------------------------------------------------------
+
+def classify_line(line: str) -> tuple[str | None, str, str | None]:
+    """Classify one content line.
+
+    Returns (slot, value, reason):
+      slot in {"DO","LIM","BAN"} with the slot value, reason None; or
+      slot None with value=original line and a reason string explaining
+      why the line stays UNCONVERTED. Only unambiguous patterns convert.
+    """
+    stripped = line.strip()
+    m = _BULLET.match(stripped)
+    numbered = bool(re.match(r"^\s*\d+[.)]", stripped))
+    body = (m.group(1) if m else stripped).strip()
+    if not body:
+        return None, line, "blank"
+
+    # 1. BAN lead-in — must survive the BAN-field guard, else it is a
+    #    BAN-rule violation and stays UNCONVERTED (never silently dropped).
+    ban_m = _BAN_LEAD.match(body)
+    if ban_m:
+        value = ban_m.group(1).strip().rstrip(".")
+        verdict = guards.validate_ban_field(value)
+        if verdict["ok"]:
+            return "BAN", value, None
+        return None, line, f"ban-rule violation: {verdict['reason']}"
+
+    # 2. conditional clause anywhere -> nuanced, do not compress.
+    cond = _CONDITIONAL.search(body)
+    if cond:
+        return None, line, f"conditional clause ({cond.group(0).strip()!r}) — nuance preserved verbatim"
+
+    # 3. standing constraint.
+    if _LIM_LEAD.match(body):
+        return "LIM", body.rstrip("."), None
+
+    # 4. imperative step (numbered lines get the benefit of list position).
+    if _DO_LEAD.match(body) or (numbered and _DO_LEAD.match(body.split(":")[0])):
+        return "DO", body.rstrip("."), None
+
+    return None, line, "unclassifiable: no unambiguous DO/LIM/BAN pattern"
+
+
+def _convert_section(sec: Section) -> SectionResult:
+    raw_lines = ([sec.heading_line] if sec.heading_line is not None else []) + sec.lines
+    result = SectionResult(index=sec.index, title=sec.title, status="empty", card=None,
+                           raw_lines=raw_lines)
+
+    content = [ln for ln in sec.lines if ln.strip()]
+    if not content:
+        # heading with no body: TASK-only card, nothing droppable.
+        result.card = codec.assemble_card({"TASK": sec.title, "sec": str(sec.index)})
+        return result
+
+    # (b) section-level nuance guard: conditional-dense prose is kept whole.
+    nu = guards.assess_nuance("\n".join(content))
+    if nu["verdict"] == "advise-skip":
+        result.status = "unconverted"
+        result.section_reason = nu["reason"]
+        result.unconverted = [(ln, "section-level nuance guard") for ln in content]
+        return result
+
+    slots: dict[str, list[str]] = {"DO": [], "LIM": [], "BAN": []}
+    in_code = False
+    for ln in content:
+        if _CODE_FENCE.match(ln):
+            in_code = not in_code
+            result.unconverted.append((ln, "code fence — preserved verbatim"))
+            continue
+        if in_code:
+            result.unconverted.append((ln, "code block — preserved verbatim"))
+            continue
+        if _SEPARATOR.match(ln):
+            result.unconverted.append((ln, "decorative separator"))
+            continue
+        slot, value, reason = classify_line(ln)
+        if slot is None:
+            result.unconverted.append((ln, reason or "unclassifiable"))
+            if reason and reason.startswith("ban-rule violation"):
+                result.ban_violations.append(ln.strip())
+        else:
+            slots[slot].append(value)
+            result.slotted.append((ln, slot, value))
+
+    if result.slotted:
+        card_slots: dict[str, Any] = {"TASK": sec.title, "sec": str(sec.index)}
+        for name in ("DO", "LIM", "BAN"):
+            if slots[name]:
+                card_slots[name] = slots[name]  # codec joins lists with ';'
+        result.card = codec.assemble_card(card_slots)
+        substantive_left = [
+            (ln, r) for ln, r in result.unconverted
+            if not r.startswith("decorative")
+        ]
+        result.status = "converted" if not substantive_left else "partial"
+    else:
+        result.status = "unconverted"
+        result.section_reason = "no unambiguous rules found — kept verbatim"
+        # ensure the heading is preserved with the body (raw_lines has it)
+
+    return result
+
+
+def convert_text(text: str, source_name: str = "<memory>") -> Conversion:
+    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+    conv = Conversion(
+        source_name=source_name,
+        source_sha256=hashlib.sha256(normalized.encode("utf-8")).hexdigest(),
+        source_text=normalized,
+    )
+    for sec in split_sections(normalized):
+        conv.sections.append(_convert_section(sec))
+    return conv
+
+
+# ---------------------------------------------------------------------------
+# (c) rendering + sidecar report
+# ---------------------------------------------------------------------------
+
+def render_hp1(conv: Conversion) -> str:
+    lines: list[str] = [
+        HPINSTR_HEADER,
+        f"#source: {conv.source_name}",
+        f"#source_sha256: {conv.source_sha256}",
+    ]
+    for sec in conv.sections:
+        if sec.status == "unconverted":
+            reason = (sec.section_reason or "unclassifiable").replace("\n", " ")
+            lines.append(f"{_UNCONV_BEGIN} sec={sec.index} reason={reason}")
+            lines.extend(sec.raw_lines)
+            lines.append(_UNCONV_END)
+            continue
+        if sec.card:
+            lines.append(sec.card)
+        leftovers = [
+            (ln, r) for ln, r in sec.unconverted
+            if not r.startswith("decorative")
+        ]
+        if leftovers:
+            lines.append(f"{_UNCONV_BEGIN} sec={sec.index} reason=partial: unclassified lines preserved")
+            for ln, r in leftovers:
+                lines.append(ln)
+            lines.append(_UNCONV_END)
+    return "\n".join(lines) + "\n"
+
+
+def build_report(conv: Conversion, hp1_text: str) -> dict[str, Any]:
+    statuses = [s.status for s in conv.sections]
+    content_lines = sum(len([ln for ln in s.raw_lines if ln.strip()]) for s in conv.sections)
+    slotted_lines = sum(len(s.slotted) for s in conv.sections)
+    unconverted_lines = sum(len(s.unconverted) for s in conv.sections)
+    before = codec.estimate_tokens(conv.source_text)
+    after = codec.estimate_tokens(hp1_text)
+    be = guards.check_breakeven(conv.source_text)
+    return {
+        "format": "hpinstr-report/1.0",
+        "source": conv.source_name,
+        "source_sha256": conv.source_sha256,
+        "sections": {
+            "total": len(conv.sections),
+            "converted": statuses.count("converted"),
+            "partial": statuses.count("partial"),
+            "unconverted": statuses.count("unconverted"),
+            "empty": statuses.count("empty"),
+        },
+        "lines": {
+            "content": content_lines,
+            "slotted": slotted_lines,
+            "unconverted": unconverted_lines,
+        },
+        "line_conversion_rate": round(slotted_lines / content_lines, 3) if content_lines else 0.0,
+        "tokens": {
+            "estimator": "chars/4 (codec.estimate_tokens)",
+            "before": before,
+            "after": after,
+            "reduction_pct": round((1 - after / before) * 100, 1) if before else 0.0,
+            # cards only, excluding verbatim UNCONVERTED blocks — shows the
+            # ceiling a sampling-assisted pass could approach.
+            "cards_only": sum(
+                codec.estimate_tokens(s.card) for s in conv.sections if s.card
+            ),
+        },
+        "below_breakeven": bool(be["passthrough"]),
+        "ban_violations": conv.ban_violations,
+        "unconverted_sections": [
+            {"sec": s.index, "title": s.title, "reason": s.section_reason}
+            for s in conv.sections if s.status == "unconverted"
+        ],
+    }
+
+
+def convert_file(src: str | Path, out: str | Path | None = None,
+                 report_path: str | Path | None = None) -> dict[str, Any]:
+    src = Path(src)
+    text = src.read_text(encoding="utf-8")
+    conv = convert_text(text, source_name=src.name)
+    hp1_text = render_hp1(conv)
+    out = Path(out) if out else src.with_suffix(".hp1")
+    report_path = Path(report_path) if report_path else Path(str(out) + ".report.json")
+    out.write_text(hp1_text, encoding="utf-8")
+    report = build_report(conv, hp1_text)
+    report["output"] = str(out)
+    report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    return report
+
+
+# ---------------------------------------------------------------------------
+# (d) --check mode: hash-based source-drift validation
+# ---------------------------------------------------------------------------
+
+def check_file(hp1_path: str | Path, source_path: str | Path) -> dict[str, Any]:
+    """Validate an existing .hp1 file against its source.
+
+    Checks: header magic, recorded sha256 vs the source's current
+    (newline-normalized) sha256, and that every embedded HP1 card still
+    parses under the current legend. Returns {"ok", "drift", ...}.
+    """
+    hp1_text = Path(hp1_path).read_text(encoding="utf-8")
+    lines = hp1_text.splitlines()
+    issues: list[str] = []
+
+    if not lines or lines[0].strip() != HPINSTR_HEADER:
+        return {"ok": False, "drift": False,
+                "issues": [f"not an HPINSTR file: missing {HPINSTR_HEADER!r} header"]}
+
+    recorded = None
+    for ln in lines[:5]:
+        if ln.startswith("#source_sha256:"):
+            recorded = ln.split(":", 1)[1].strip()
+            break
+    if recorded is None:
+        issues.append("no #source_sha256 line in header")
+
+    src_text = Path(source_path).read_text(encoding="utf-8")
+    normalized = src_text.replace("\r\n", "\n").replace("\r", "\n")
+    current = hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+    drift = recorded is not None and recorded != current
+    if drift:
+        issues.append(
+            f"source drift: recorded sha256 {recorded[:12]}... != current {current[:12]}... — re-run convert"
+        )
+
+    cards_checked = 0
+    in_unconv = False
+    for ln in lines:
+        if ln.startswith(_UNCONV_BEGIN):
+            in_unconv = True
+            continue
+        if ln.strip() == _UNCONV_END:
+            in_unconv = False
+            continue
+        if not in_unconv and ln.startswith(_HP1_PREFIX):
+            cards_checked += 1
+            try:
+                codec.parse_card(ln)
+            except codec.CodecError as exc:
+                issues.append(f"card {cards_checked} invalid: {exc}")
+
+    return {
+        "ok": not issues,
+        "drift": drift,
+        "recorded_sha256": recorded,
+        "current_sha256": current,
+        "cards_checked": cards_checked,
+        "issues": issues,
+    }
+
+
+# ---------------------------------------------------------------------------
+# CLI: hp-instructions
+# ---------------------------------------------------------------------------
+
+def _print_json(obj: Any) -> None:
+    """Print JSON; fall back to ASCII escapes on narrow consoles (cp949 etc.)."""
+    try:
+        print(json.dumps(obj, ensure_ascii=False, indent=2))
+    except UnicodeEncodeError:
+        print(json.dumps(obj, ensure_ascii=True, indent=2))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="hp-instructions",
+        description="Convert recurring-instruction files (CLAUDE.md style) into HP1 instruction cards.",
+    )
+    parser.add_argument("source", help="instruction file to convert (or source file in --check mode)")
+    parser.add_argument("-o", "--out", help="output .hp1 path (default: <source>.hp1)")
+    parser.add_argument("--report", help="sidecar report path (default: <out>.report.json)")
+    parser.add_argument("--check", metavar="HP1_FILE",
+                        help="validate this existing .hp1 against SOURCE for drift instead of converting")
+    parser.add_argument("--license", metavar="KEY", default=None,
+                        help="license key (default discovery: $HP_LICENSE, then ~/.handoffpack/license)")
+    args = parser.parse_args(argv)
+
+    if args.check:
+        # --check (drift scan) is FREE — no license required.
+        result = check_file(args.check, args.source)
+        _print_json(result)
+        return 0 if result["ok"] else (2 if result.get("drift") else 1)
+
+    # Full conversion run is a paid feature: 'plus' tier, verified offline.
+    ok, msg, _payload = hplicense.require_tier("plus", args.license)
+    if not ok:
+        _print_json({"error": "license_required", "detail": msg,
+                     "hint": "hp-instructions --check remains free; full conversion needs a 'plus' key"})
+        return 3
+
+    report = convert_file(args.source, args.out, args.report)
+    _print_json(report)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())