fix: harden output boundaries and provider verification

Release as deckflow-core 0.1.1.

Author: Garfield-yin

README.md

@@ -23,8 +23,8 @@ virtualenv, or vendored into a Skill with no install step at all.
 
 ```bash
 # Managed install — no venv, no pipx, no uv, works on a PEP 668 interpreter
-python3 -m pip install --target ~/.deckflow/core/0.1.0 deckflow-core==0.1.0
-PYTHONPATH=~/.deckflow/core/0.1.0 python3 -m deckflow_core providers
+python3 -m pip install --target ~/.deckflow/core/0.1.1 deckflow-core==0.1.1
+PYTHONPATH=~/.deckflow/core/0.1.1 python3 -m deckflow_core providers
 ```
 
 ```bash
@@ -224,7 +224,7 @@ deterministically so two isolated runs over the same inputs produce the same
 report bytes.
 
 ```json
-{"schema_version": 1, "command": "providers", "core_version": "0.1.0",
+{"schema_version": 1, "command": "providers", "core_version": "0.1.1",
  "status": "succeeded", "started_at": "...", "finished_at": "...",
  "providers": [], "inputs": [], "outputs": [], "diagnostics": []}
 ```
@@ -246,8 +246,10 @@ A failure still prints a parseable envelope on stdout; prose goes to stderr.
 
 ## Scope of this release
 
-v0.1.0 registers `providers`, `parse`, `editor` and `export pptx` — the whole
-planned surface.
+v0.1.1 registers `providers`, `parse`, `editor` and `export pptx` — the whole
+planned surface. This patch release hardens report/output collision handling,
+Parse Bundle replacement, editor page boundaries and provider version
+verification, and reports editor crashes after readiness as failures.
 
 `validate html` is deferred beyond 0.1.x and is not registered at all: a
 deferred command may not ship as a stub, a placeholder, or a "not implemented"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "deckflow-core"
-version = "0.1.0"
+version = "0.1.1"
 description = "Deckflow capability broker: one CLI over deckflow-extract, html-editor and deckhtml, with on-demand provider acquisition."
 requires-python = ">=3.10"
 license = "MIT"

src/deckflow_core/__init__.py

@@ -15,7 +15,7 @@
 
 from pathlib import Path
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 SCHEMA_VERSION = 1
 
 

src/deckflow_core/cli.py

@@ -21,7 +21,7 @@
 from .commands import editor as editor_cmd, export_pptx, parse as parse_cmd, providers_cmd
 from .diagnostics import Diagnostic
 from .envelope import STATUS_FAILED, Envelope
-from .exits import EXIT_INTERRUPT, EXIT_OK, EXIT_USAGE, CoreError
+from .exits import EXIT_INTERRUPT, EXIT_OK, EXIT_OUTPUT, EXIT_USAGE, CoreError
 from .fsutil import atomic_write_text
 from .providers import resolve as resolver
 
@@ -226,6 +226,95 @@ def _normalize(options: argparse.Namespace) -> argparse.Namespace:
     return options
 
 
+def _prepare_report_path(options: argparse.Namespace) -> None:
+    """Resolve and validate the report before any provider or project can run.
+
+    A report is an output in its own right. It may not alias another output,
+    overwrite an input, or land inside the canonical ``project/deck`` tree.
+    Clearing ``options.report`` before validation also ensures that a rejected
+    report path is never used while emitting the failure envelope.
+    """
+    raw = getattr(options, "report", None)
+    if not raw:
+        return
+
+    options.report = None
+    report = Path(raw).expanduser().resolve()
+    conflicts: list[tuple[str, Path]] = []
+
+    def protect(label: str, value: str | Path | None) -> None:
+        if value is None:
+            return
+        protected = Path(value).expanduser().resolve()
+        if report == protected:
+            conflicts.append((label, protected))
+
+    protect("input", getattr(options, "input", None))
+    protect("output", getattr(options, "output", None))
+    protect("browser executable", getattr(options, "browser", None))
+    for name, path in getattr(options, "provider_bins", {}).items():
+        protect(f"{name} provider executable", path)
+
+    if getattr(options, "command", None) == "parse":
+        output_root = Path(options.out).expanduser().resolve()
+        if report == output_root or output_root in report.parents:
+            conflicts.append(("parse output directory", output_root))
+
+    project_value = getattr(options, "project", None)
+    if project_value:
+        project_root = Path(project_value).expanduser().resolve()
+        deck_root = project_root / "deck"
+        if report == deck_root or deck_root in report.parents:
+            conflicts.append(("canonical deck tree", deck_root))
+        for relative in ("deck-plan.json", "intent-detail.json"):
+            protect(f"project record {relative}", project_root / relative)
+
+    if conflicts:
+        label, protected = conflicts[0]
+        raise CoreError(
+            Diagnostic(
+                rule_id="REPORT_PATH_CONFLICT",
+                severity="error",
+                message=f"The report path conflicts with the command's {label}.",
+                location=str(report),
+                expected="a distinct report path that cannot overwrite command inputs or outputs",
+                actual=f"same as or inside {protected}",
+                recovery="Choose a separate --report path outside the parse bundle and canonical deck tree.",
+            ),
+            exit_code=EXIT_OUTPUT,
+        )
+
+    if report.is_dir():
+        raise CoreError(
+            Diagnostic(
+                rule_id="REPORT_NOT_A_FILE",
+                severity="error",
+                message="The report target is a directory.",
+                location=str(report),
+                expected="a JSON file path",
+                actual="an existing directory",
+                recovery="Choose a file path for --report.",
+            ),
+            exit_code=EXIT_OUTPUT,
+        )
+
+    overwrite = bool(getattr(options, "overwrite", False))
+    if report.exists() and not overwrite:
+        raise CoreError(
+            Diagnostic(
+                rule_id="REPORT_EXISTS",
+                severity="error",
+                message="The report target already exists.",
+                location=str(report),
+                expected="a new report path, or an explicit --overwrite",
+                actual="an existing path",
+                recovery="Choose another --report path, or pass --overwrite on commands that support it.",
+            ),
+            exit_code=EXIT_OUTPUT,
+        )
+    options.report = str(report)
+
+
 def _emit(envelope: Envelope, human: str | None, report: str | None) -> None:
     payload = envelope.dumps()
     if report:
@@ -250,6 +339,7 @@ def main(argv: Sequence[str] | None = None) -> int:
 
     try:
         options = _normalize(options)
+        _prepare_report_path(options)
         if options.command == "providers":
             envelope, human, code = providers_cmd.run(options)
         elif options.command == "editor":

src/deckflow_core/commands/editor.py

@@ -39,6 +39,7 @@
 
 _ELEMENT_ID_RE = re.compile(r"""data-element-id\s*=\s*["']([^"']+)["']""")
 _URL_RE = re.compile(r"https?://[0-9A-Za-z\.\-]+:\d+\S*")
+_SLIDE_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
 # The provider's own working files. They appear under the project root by
 # design, so they are expected artefacts rather than boundary violations.
 _EDITOR_ARTEFACTS = (".local-html-editor",)
@@ -106,7 +107,23 @@ def _preflight(root: Path, page: str | None) -> tuple[Path, Path]:
             ),
             exit_code=EXIT_INPUT,
         )
-    pages = sorted(pages_dir.glob("*.html"))
+    pages_root = pages_dir.resolve()
+    page_candidates = sorted(candidate for candidate in pages_dir.glob("*.html") if candidate.is_file())
+    escaped = [candidate for candidate in page_candidates if candidate.resolve().parent != pages_root]
+    if escaped:
+        raise CoreError(
+            Diagnostic(
+                rule_id="EDITOR_PAGE_ESCAPES_ROOT",
+                severity="error",
+                message="A canonical page resolves outside deck/pages/.",
+                location=str(escaped[0]),
+                expected=f"a direct HTML file inside {pages_root}",
+                actual=str(escaped[0].resolve()),
+                recovery="Replace the escaping symlink with a real canonical page inside deck/pages/.",
+            ),
+            exit_code=EXIT_INPUT,
+        )
+    pages = [candidate.resolve() for candidate in page_candidates]
     if not pages:
         raise CoreError(
             Diagnostic(
@@ -121,15 +138,29 @@ def _preflight(root: Path, page: str | None) -> tuple[Path, Path]:
             exit_code=EXIT_INPUT,
         )
     if page is None:
-        return deck_dir, pages_dir
-    target = pages_dir / f"{page}.html"
-    if not target.is_file():
+        return deck_dir, pages_root
+    if not _SLIDE_ID_RE.fullmatch(page):
+        raise CoreError(
+            Diagnostic(
+                rule_id="EDITOR_PAGE_ID_INVALID",
+                severity="error",
+                message="The requested page is not a safe slide id.",
+                location=page,
+                expected="an alphanumeric slide id containing only letters, digits, dot, underscore, or hyphen",
+                actual=page,
+                recovery="Pass the stem of a direct deck/pages/*.html file, without path separators or `..`.",
+            ),
+            exit_code=EXIT_INPUT,
+        )
+    pages_by_id = {candidate.stem: candidate for candidate in pages}
+    target = pages_by_id.get(page)
+    if target is None:
         raise CoreError(
             Diagnostic(
                 rule_id="EDITOR_PAGE_NOT_FOUND",
                 severity="error",
                 message=f"No canonical page named {page}.",
-                location=str(target),
+                location=str(pages_root / f"{page}.html"),
                 expected=f"one of: {', '.join(p.stem for p in pages)}",
                 actual=page,
                 recovery="Pass --page with a slide id that exists, or omit it to open all pages.",
@@ -318,8 +349,11 @@ def run(options: Any) -> tuple[Envelope, str | None, int]:
     )
     stdout_lines: list[str] = []
     stderr_lines: list[str] = []
+    drainers: list[threading.Thread] = []
     for stream, sink in ((child.stdout, stdout_lines), (child.stderr, stderr_lines)):
-        threading.Thread(target=_drain, args=(stream, sink), daemon=True).start()
+        thread = threading.Thread(target=_drain, args=(stream, sink), daemon=True)
+        thread.start()
+        drainers.append(thread)
 
     url = _await_ready(stdout_lines, child)
     if url is None:
@@ -345,16 +379,36 @@ def run(options: Any) -> tuple[Envelope, str | None, int]:
     sys.stderr.write("[deckflow] press Ctrl-C when you are done editing\n")
 
     interrupted = _wait_for_session_end(child)
+    for thread in drainers:
+        thread.join(timeout=1)
+    provider_exit_code = child.poll()
+    provider_failed = not interrupted and provider_exit_code != 0
+    provider_output = summarize_output("\n".join(stderr_lines), "\n".join(stdout_lines))
 
     after = _snapshot(deck_dir)
     changed_pages, findings = _classify(before, after)
     envelope.extend(findings)
+    if provider_failed:
+        envelope.add(
+            Diagnostic(
+                rule_id="EDITOR_PROVIDER_EXITED",
+                severity="error",
+                message="The editor provider exited unexpectedly after announcing readiness.",
+                location=str(target),
+                expected="exit code 0, or a session ended by the supervising interrupt",
+                actual=f"exit code {provider_exit_code}: {provider_output}",
+                recovery="Restore any affected pages from the editor backups, then re-run the session.",
+            )
+        )
     envelope.extra.update({
         "event": "finished",
         "session_id": session_id,
         "project": str(deck_dir.parent),
         "changed_pages": changed_pages,
-        "ended_by": "interrupt" if interrupted else "editor-exit",
+        "ended_by": (
+            "interrupt" if interrupted else "provider-error" if provider_failed else "editor-exit"
+        ),
+        "provider_exit_code": provider_exit_code,
         "backups": str(deck_dir / ".local-html-editor" / "backups"),
     })
 
@@ -388,4 +442,6 @@ def run(options: Any) -> tuple[Envelope, str | None, int]:
 
     has_error = any(d.severity == "error" for d in envelope.diagnostics)
     envelope.status = STATUS_FAILED if has_error else STATUS_SUCCEEDED
+    if provider_failed:
+        return envelope, None, EXIT_EXECUTION
     return envelope, None, EXIT_CONTRACT if has_error else EXIT_OK

src/deckflow_core/commands/parse.py

@@ -29,7 +29,7 @@
     file_record,
 )
 from ..exits import EXIT_EXECUTION, EXIT_INPUT, EXIT_OK, EXIT_OUTPUT, CoreError
-from ..fsutil import deckflow_home, require_empty_dir, sha256_file
+from ..fsutil import deckflow_home, require_empty_dir, resolve_within, sha256_file
 from ..providers import matrix
 from ..providers import resolve as resolver
 
@@ -142,6 +142,81 @@ def _bundle_outputs(out: Path) -> list[dict[str, Any]]:
     return outputs
 
 
+def _refuse_unsafe_overwrite(out: Path, actual: str) -> None:
+    raise CoreError(
+        Diagnostic(
+            rule_id="PARSE_OVERWRITE_UNOWNED",
+            severity="error",
+            message="Refusing to replace a directory that is not a valid Parse Bundle.",
+            location=str(out),
+            expected=(
+                "a deckflow-extract bundle containing a valid parse-manifest.json, "
+                "document, and assets directory"
+            ),
+            actual=actual,
+            recovery="Choose a new --out directory. Move unrelated files manually if they are no longer needed.",
+        ),
+        exit_code=EXIT_OUTPUT,
+    )
+
+
+def _require_safe_output(out: Path, *, overwrite: bool) -> None:
+    """Allow replacement only for a complete deckflow-extract-owned bundle."""
+    require_empty_dir(out, overwrite=overwrite)
+    if not out.exists() or not any(out.iterdir()) or not overwrite:
+        return
+
+    manifest_path = out / _MANIFEST
+    if manifest_path.is_symlink() or not manifest_path.is_file():
+        _refuse_unsafe_overwrite(out, "missing a direct parse-manifest.json file")
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as error:
+        _refuse_unsafe_overwrite(out, f"unreadable parse-manifest.json: {error}")
+    if not isinstance(manifest, dict):
+        _refuse_unsafe_overwrite(out, "parse-manifest.json is not a JSON object")
+
+    tool = manifest.get("tool")
+    outputs = manifest.get("outputs")
+    schema_version = manifest.get("schema_version")
+    if (
+        not isinstance(tool, dict)
+        or tool.get("name") != "deckflow-extract"
+        or not isinstance(schema_version, int)
+        or schema_version < 1
+        or not isinstance(outputs, dict)
+    ):
+        _refuse_unsafe_overwrite(out, "manifest ownership or schema fields are invalid")
+
+    document_value = outputs.get("document")
+    assets_value = outputs.get("assets_dir")
+    if not isinstance(document_value, str) or not isinstance(assets_value, str):
+        _refuse_unsafe_overwrite(out, "manifest output paths are missing or invalid")
+    try:
+        document = resolve_within(out, Path(document_value))
+        assets = resolve_within(out, Path(assets_value))
+    except CoreError:
+        _refuse_unsafe_overwrite(out, "manifest output paths escape the bundle directory")
+    if not document.is_file() or not assets.is_dir():
+        _refuse_unsafe_overwrite(out, "manifest output files are incomplete")
+
+
+def _require_input_outside_output(source: Path, out: Path) -> None:
+    if source == out or out in source.parents:
+        raise CoreError(
+            Diagnostic(
+                rule_id="PARSE_OUTPUT_CONTAINS_INPUT",
+                severity="error",
+                message="The Parse Bundle output directory contains the input file.",
+                location=str(out),
+                expected="an output directory separate from the input file",
+                actual=str(source),
+                recovery="Choose --out outside the directory tree containing the input.",
+            ),
+            exit_code=EXIT_OUTPUT,
+        )
+
+
 def _carry_diagnostics(envelope: Envelope, provider_result: dict[str, Any]) -> None:
     """Surface the provider's own findings without re-judging them."""
     for entry in provider_result.get("diagnostics") or ():
@@ -181,7 +256,8 @@ def run(options: Any) -> tuple[Envelope, str | None, int]:
     envelope = Envelope(command=COMMAND)
     source = _resolve_input(options.input)
     out = Path(options.out).expanduser().resolve()
-    require_empty_dir(out, overwrite=options.overwrite)
+    _require_input_outside_output(source, out)
+    _require_safe_output(out, overwrite=options.overwrite)
 
     spec = matrix.get("extract", options.provider_specs)
     resolution = resolver.resolve(