administrator/DocForge2
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions Pages

feat: add deterministic preview rendering

Browse source
This commit is contained in:
Andraxion 2026-07-22 03:32:05 -04:00
parent 8c75f4f44d
commit 411f417670
23 changed files with 1413 additions and 142 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/CONTRACT.md
View file

@ -1,4 +1,4 @@
# DocForge 0.2 contract
# DocForge 0.3 contract
## Authority boundary
@ -18,7 +18,7 @@ commit when Git is available; it cannot change repository state.
- Result envelope: `schemas/result.schema.json`, version 1.
- Changeset schema: `schemas/changeset.schema.json`, version 1.
- Index schema: version 1, disposable and reproducible.
- Core, CLI, and MCP server: version 0.2.0.
- Core, CLI, and MCP server: version 0.3.0.
Schema files describe the generic interchange contract. Runtime validation remains responsible for
path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
@ -58,5 +58,23 @@ sources. A stale canonical base, stale node hash, stale changeset hash, unauthor
path, invalid graph, dependency cycle, unresolved delete relationship, or configured limit fails
before the proposal file changes.
Normal MCP access does not expose canonical application, arbitrary file writes, previews, renderer
execution, shell commands, Git mutation, build commands, deployment, or publication.
## Declared rendering and previews
Render configuration is optional. A configured project declares one template root, one isolated
preview root, and one or more stable view IDs. Each view names a built-in renderer, template,
derived output file, title, and optional family filter. Paths are resolved under the project root
and may not overlap canonical content, authority files, changesets, templates, or previews.
The initial `generic_html` renderer uses pinned CommonMark parsing with raw HTML disabled. Templates
are UTF-8 files with a fixed token vocabulary; they cannot name commands, modules, or executable
renderers. Render identity covers the canonical source hash, optional changeset hash, selected node
and edge identities, view configuration, template hash, renderer contract, and exact parser version.
An explicit CLI render atomically replaces one declared derived output. MCP can render a validated
changeset only to its isolated preview path. Status recomputes expected output without writing and
reports `current`, `stale`, `missing`, `unsafe`, or `oversized`. Input changes detected before atomic
replacement fail without replacing the prior output.
Normal MCP access does not expose canonical application, declared project-output rendering,
arbitrary renderer execution, arbitrary file writes, shell commands, Git mutation, build commands,
deployment, or publication.

19
docs/MCP_CONTRACT.md
View file

@ -32,16 +32,25 @@ response includes project identity, revision, source hash, adapter version, and
- `docforge_propose_node_delete`
- `docforge_validate_changeset`
- `docforge_get_changeset_diff`
- `docforge_preview_changeset`
Proposal tools may write only below the configured changeset root. They never change canonical
files. Without `--proposal-writer`, mutation tools return `proposal_access_disabled`. Validation and
diff retrieval remain available for existing changesets.
Proposal tools may write only below the configured changeset or isolated preview roots. They never
change canonical files or declared project output. Without `--proposal-writer`, changeset mutation
tools return `proposal_access_disabled`. Validation, diff retrieval, and preview remain available
for existing changesets. A preview accepts a declared view ID, not a renderer name or command.
## Render boundary
`docforge_render_status` recomputes expected hashes without writing. `docforge_preview_changeset`
runs only a project-declared view through DocForge's fixed built-in renderer registry and writes one
atomic HTML file below the configured preview root. Rendering declared project output is available
only through the explicit local CLI integration command.
## Excluded tools
The normal server never exposes shell execution, arbitrary reads or writes, canonical changeset
application, preview generation, renderer execution, Git mutation, project builds, deployment,
publication, global project selection, or cross-project retrieval.
application, declared project-output rendering, arbitrary renderer execution, Git mutation, project
builds, deployment, publication, global project selection, or cross-project retrieval.
DocForge pins the official stable Python MCP SDK to the compatible `mcp>=1.28,<2` release line.
Migration to a later major release requires a separate contract and protocol compatibility review.